@polymorphism-tech/morph-spec 7.7.3 → 7.8.1

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

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-brainstorming
@@ -27,7 +27,7 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
 | Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
 | Jobs async | Hangfire — apenas se a feature requer processamento em background |
 
-**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions sem result pattern, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
+**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions sem result pattern, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
 
 ## O que fazer
 
@@ -82,9 +82,13 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
 
    **Decisão de pausa** (regras da tabela do MORPH.md §5): `trust: manual` → pausa sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → auto-passa (`pause: false`). Monte `reason` com o sinal que disparou.
 
-   **Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
-   `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
-   (Edit em `.morph/features/**` é permitido pela allowlist). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
+   **Persista a decisão ANTES de apresentar ou auto-aprovar — via CLI, nunca editando feature.json à mão** (o Edit manual colide com o hook state-sync, que reescreve o arquivo entre o seu Read e o Edit — erro "file modified since read"):
+
+   ```
+   morph-spec gate-decision {feature} proposal --pause false --reason "nenhum sinal de risco" --signals '{"designSystemDivergence":false,"standardsViolations":[]}'
+   ```
+
+   O comando grava `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt }` no `feature.json` autoritativo com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
 
    **Se `pause === true`** (manual mode OU risco detectado em auto), use `AskUserQuestion`:
 

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

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "7.7.3"
+cliVersion: "7.8.0"
 ---
 
 # morph-implement

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

@@ -4,7 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-plan
@@ -34,9 +34,10 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
      - `Guid.NewGuid()` → usar `Guid.CreateVersion7()`
      - Classes não-sealed sem justificativa documentada
      - Exceptions como fluxo de controle → usar result pattern com `result.Match()`
-     - Camada de Service/Manager entre handler e dados → handler usa `IRepository<T>` ou `DbContext` direto
+     - Camada de Service/Manager entre handler e dados → handler usa `ApplicationDbContext` direto no slice
+     - Repository genérico (`IRepository<T>`/`IUnitOfWork`) → redundante sobre EF Core: `DbSet<T>` já é repository, `DbContext` já é unit of work
      - SQL cru (`FromSqlRaw`, `ExecuteQuery(string)`) sem justificativa em `decisions.md` → usar LINQ
-   - Política de acesso a dados (registre no mandate como orientação, não proibição): `IRepository<T>` + `IUnitOfWork` para CRUD simples; `ApplicationDbContext` injetado direto no slice para queries específicas (joins, projeção, paginação).
+   - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
    - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - Checklist de done com critérios verificáveis por tarefa.
 
@@ -84,9 +85,13 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
    **Decisão de pausa** (regras da tabela do MORPH.md §5): `trust: manual` → pausa sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; `taskCount > 20` → pausa; caso contrário → auto-passa (`pause: false`).
 
-   **Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
-   `gateDecisions.plan = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
-   (Edit em `.morph/features/**` é permitido pela allowlist). Isso deixa o raciocínio de trust auditável no disco: o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com esta decisão e avisa em caso de divergência. Sem este registro o guard não tem como verificar — não pule.
+   **Persista a decisão ANTES de apresentar ou auto-aprovar — via CLI, nunca editando feature.json à mão** (o Edit manual colide com o hook state-sync, que reescreve o arquivo entre o seu Read e o Edit — erro "file modified since read"):
+
+   ```
+   morph-spec gate-decision {feature} plan --pause false --reason "nenhum sinal de risco" --signals '{"taskCount":12,"standardsViolations":[]}'
+   ```
+
+   O comando grava `gateDecisions.plan = { pause, reason, signals, trust, decidedAt }` no `feature.json` autoritativo com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`). Isso deixa o raciocínio de trust auditável no disco: o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com esta decisão e avisa em caso de divergência. Sem este registro o guard não tem como verificar — não pule.
 
    **Se `pause === true`**, use `AskUserQuestion`:
 

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-proposal

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-review
@@ -46,14 +46,20 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          (architecture 30%, contracts 25%, code-quality 25%, test-coverage 20%)
          seguindo as bandas 0-10 de cada uma.
          NÃO reescreva código. NÃO toque em tasks.json, feature.json nem no board
-         de sessão. Ao concluir, ENTREGUE o relatório final — terminar idle sem
-         reportar é falha de protocolo.
-         Retorne: score 0-10 por dimensão, score composto (arch×0.30 + contracts×0.25
-         + quality×0.25 + tests×0.20), e feedback priorizado (bloqueantes primeiro)
-         para qualquer dimensão < 9.
+         de sessão.
+         Protocolo obrigatório — ATO FINAL: antes de encerrar, chame a tool
+         SendMessage com to:"main" e o relatório completo no content; sua última
+         mensagem em texto NÃO chega ao orquestrador — só SendMessage chega.
+         Exemplo literal (última chamada de tool da sua sessão):
+         SendMessage({ to: "main", content: "Review de {feature}: arch=9.0
+         contracts=9.5 quality=9.0 tests=8.5 → composto 9.05. Feedback: ..." })
+         Terminar idle sem SendMessage é falha de protocolo.
+         Retorne no content: score 0-10 por dimensão, score composto (arch×0.30 +
+         contracts×0.25 + quality×0.25 + tests×0.20), e feedback priorizado
+         (bloqueantes primeiro) para qualquer dimensão < 9.
      ```
    - **Fallback (tipo não registrado):** se `morph-evaluator` não estiver na sua lista de subagent types, despache `general-purpose` colando o campo `persona` do agente `evaluator` (Read em `.morph/framework/agents.json`) no topo do prompt — e **registre o fallback no review-report** (seção de método).
-   - Os scores por dimensão e o composto do review-report vêm **desse retorno**, não da sua auto-avaliação. Se o avaliador ficar idle sem reportar, cobre via SendMessage antes de prosseguir.
+   - Os scores por dimensão e o composto do review-report vêm **desse retorno**, não da sua auto-avaliação. O hook `subagent-report-guard` bloqueia uma vez o encerramento do avaliador sem SendMessage; se mesmo assim ele ficar idle sem reportar, cobre via SendMessage antes de prosseguir (fallback).
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-stack-scan
@@ -29,7 +29,7 @@ Quando o projeto já tem código existente e você precisa entender o estado atu
 | Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
 | Jobs | Hangfire (apenas quando necessário) |
 
-**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
+**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
 
 ## Greenfield short-circuit
 
@@ -62,7 +62,7 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    - Erros: Result pattern (`result.Match()`)
 
    ## Padrões proibidos
-   `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
+   `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
 
    ## Recomendação
    Compliance trivial (greenfield). Prosseguir para morph-brainstorming.
@@ -82,7 +82,7 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    BACKEND:
    - Todos os .csproj: qual TargetFramework? Quais PackageReferences relevantes?
    - Procure por: Guid.NewGuid() vs Guid.CreateVersion7(), sealed classes, result pattern vs exceptions
-   - Estrutura de src/: segue feature-folder (VSA)? Tem Controllers? Tem IRepository<T>?
+   - Estrutura de src/: segue feature-folder (VSA)? Tem Controllers? Tem repository genérico (IRepository<T>/IUnitOfWork)? Se tiver, reporte como código morto: liste onde está registrado no DI e quantos consumidores reais existem em src/ e tests/
    - Migrations/: qual ORM? Neon/Postgres ou outro banco?
    - Microsoft.Agents.* ou Microsoft.Extensions.AI nos PackageReferences?
 
@@ -102,7 +102,7 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    | Severidade | Critério |
    |------------|---------|
    | **Bloqueante** | Runtime diferente (.NET 8 ou anterior), ORM diferente (Dapper puro sem EF Core), banco diferente (MySQL, SQL Server) |
-   | **Alto** | `Guid.NewGuid()` generalizado, camada de Service/Manager entre handler e dados, SQL cru generalizado, exceptions como fluxo de controle |
+   | **Alto** | `Guid.NewGuid()` generalizado, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`) presente — código morto: migração é deletar a pasta `Repository/` + as 2 linhas de DI, SQL cru generalizado, exceptions como fluxo de controle |
    | **Médio** | Classes não-sealed, Pages Router em vez de App Router, biblioteca de UI diferente |
    | **Baixo** | Versões de pacotes desatualizadas mas compatíveis |
 

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

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "7.7.3"
+cliVersion: "7.8.1"
 ---
 
 # morph-standards

package/framework/standards/STANDARDS.json

@@ -883,7 +883,7 @@
         "endpoint": "#complete-endpoint-example",
         "registration": "#programcs-di-registration-order"
       },
-      "digest": "Each VSA feature is 5 files: Request, Response, Handler, Validator, Endpoint. Use IHandler<TReq,TRes> (not MediatR). Sealed records for DTOs, primary constructors for DI, Guid.CreateVersion7() for IDs. Handler calls Repository+UnitOfWork directly — no service layer. CancellationToken in every async call."
+      "digest": "Each VSA feature is 5 files: Request, Response, Handler, Validator, Endpoint. Use IHandler<TReq,TRes> (not MediatR). Sealed records for DTOs, primary constructors for DI, Guid.CreateVersion7() for IDs. Handler injects ApplicationDbContext directly — no service layer, no generic repository (DbSet<T> is the repository, DbContext is the unit of work). CancellationToken in every async call."
     },
     {
       "id": "backend-integrations-asaas-asaas-api",

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

@@ -1,160 +1,160 @@
-# Agent Session — Conversation state and chat reducers
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
-> **Read by Claude in:** implement
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Quando usar AgentSession
-
-Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
-
-**Use AgentSession quando:**
-- Existe uma interface de chat (web, mobile, CLI interativo)
-- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
-- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
-
-**NÃO use AgentSession quando:**
-- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
-- Agentes stateless em pipeline multi-agent — cada chamada é independente
-- Jobs de batch/background — não há conversa; histórico não faz sentido
-
-> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
-> Só adicione quando uma UI de chat real existe.
-
----
-
-## A API
-
-**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
-
-**Tipos confirmados via context7:**
-- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
-- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
-- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
-- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
-- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
-
-```csharp
-// Construção do agente com histórico em memória
-AIAgent agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        ChatOptions = new() { Instructions = "You are a helpful assistant." },
-        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
-    });
-```
-
----
-
-## Exemplo C# — agente conversacional com session persistente entre turnos
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-// ── 1. Registrar o agente conversacional no DI ──
-// Program.cs
-builder.Services.AddSingleton<AIAgent>(sp =>
-{
-    var registry = sp.GetRequiredService<ModelRegistry>();
-    return registry.GetChatClient("text-default")
-        .AsAIAgent(new ChatClientAgentOptions
-        {
-            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
-            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
-            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
-            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
-            // não compartilham estado. O provider em si é stateless; o estado fica na session.
-            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
-            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
-        });
-});
-
-// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
-// ChatController.cs ou ChatHub.cs
-public class ChatService(AIAgent _agent)
-{
-    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
-    public async Task<AgentSession> StartConversationAsync()
-        => await _agent.CreateSessionAsync();
-
-    // Cada mensagem do usuário passa a mesma session
-    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
-    {
-        AgentResponse response = await _agent.RunAsync(userMessage, session);
-        return response.Text;
-    }
-}
-
-// ── 3. Uso no controller/hub ──
-// Primeiro turno
-AgentSession session = await chatService.StartConversationAsync();
-string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
-// reply1: "Vou verificar o pedido #1234 para você..."
-
-// Segundo turno — o agente lembra do contexto anterior
-string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
-// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
-```
-
----
-
-## History management
-
-O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
-
-### Estratégias
-
-| Estratégia | Quando usar | Como implementar |
-|------------|-------------|------------------|
-| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
-| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
-| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
-
-> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
-> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
-> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
-> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
-> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
-> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
-> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Problema |
-|-------------|----------|
-| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
-| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
-| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
-| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
-| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
-- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
-- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
-- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
-- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
-
----
-
-## References
-
-- `ai-agents-setup` — packages e DI base
-- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
-- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
-- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*
+# Agent Session — Conversation state and chat reducers
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
+> **Read by Claude in:** implement
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar AgentSession
+
+Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
+
+**Use AgentSession quando:**
+- Existe uma interface de chat (web, mobile, CLI interativo)
+- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
+- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
+
+**NÃO use AgentSession quando:**
+- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
+- Agentes stateless em pipeline multi-agent — cada chamada é independente
+- Jobs de batch/background — não há conversa; histórico não faz sentido
+
+> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
+> Só adicione quando uma UI de chat real existe.
+
+---
+
+## A API
+
+**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
+
+**Tipos confirmados via context7:**
+- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
+- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
+- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
+- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
+- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
+
+```csharp
+// Construção do agente com histórico em memória
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant." },
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+    });
+```
+
+---
+
+## Exemplo C# — agente conversacional com session persistente entre turnos
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// ── 1. Registrar o agente conversacional no DI ──
+// Program.cs
+builder.Services.AddSingleton<AIAgent>(sp =>
+{
+    var registry = sp.GetRequiredService<ModelRegistry>();
+    return registry.GetChatClient("text-default")
+        .AsAIAgent(new ChatClientAgentOptions
+        {
+            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
+            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
+            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
+            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
+            // não compartilham estado. O provider em si é stateless; o estado fica na session.
+            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+        });
+});
+
+// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
+// ChatController.cs ou ChatHub.cs
+public class ChatService(AIAgent _agent)
+{
+    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
+    public async Task<AgentSession> StartConversationAsync()
+        => await _agent.CreateSessionAsync();
+
+    // Cada mensagem do usuário passa a mesma session
+    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
+    {
+        AgentResponse response = await _agent.RunAsync(userMessage, session);
+        return response.Text;
+    }
+}
+
+// ── 3. Uso no controller/hub ──
+// Primeiro turno
+AgentSession session = await chatService.StartConversationAsync();
+string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
+// reply1: "Vou verificar o pedido #1234 para você..."
+
+// Segundo turno — o agente lembra do contexto anterior
+string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
+// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
+```
+
+---
+
+## History management
+
+O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
+
+### Estratégias
+
+| Estratégia | Quando usar | Como implementar |
+|------------|-------------|------------------|
+| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
+| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
+| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
+
+> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
+> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
+> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
+> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
+> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
+> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
+> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
+| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
+| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
+| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
+| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
+- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
+- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
+- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
+- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
+
+---
+
+## References
+
+- `ai-agents-setup` — packages e DI base
+- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
+- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
+- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*