@polymorphism-tech/morph-spec 8.32.0 → 8.34.2

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: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-brainstorming

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: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-hotfix

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: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-implement
@@ -84,6 +84,8 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
       (`morph-spec verify`) é do orquestrador, pós-batch. Em batch COM
       `isolation: "worktree"`, rode build/test no seu worktree, commite na
       branch do worktree como último ato antes do relatório — nunca faça merge.
+      Worktree não commitado NÃO é removido pelo hook e vira pendência do
+      `doctor`; o commit é o que torna o seu trabalho integrável.
 
    Seu relatório (no arquivo, e na mensagem final quando ela chega) deve conter
    APENAS: (1) o que foi feito em 2-3 frases, (2) arquivos modificados,

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-plan
@@ -138,8 +138,11 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
      - **Base URL vinda do ambiente:** o harness dá a cada feature um bloco de portas próprio (para
        duas worktrees não brigarem pela porta 3000), então o `playwright.config.ts` **não pode**
        cravar a URL — leia `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``
-       e faça o compose publicar `"${PORT:-3000}:3000"`. Config cravada = suíte batendo em porta
-       vazia e `ECONNREFUSED` com cara de app quebrada. Se estiver cravado, **isso é uma task**.
+       e faça o compose publicar `"${PORT:-3000}:3000"` e `"${POSTGRES_PORT:-5432}:5432"`, sem
+       `container_name` (o projeto compose já namespaceia; nome explícito colide entre worktrees —
+       standard `infrastructure/docker/local-compose-isolation`). Config cravada = suíte batendo em
+       porta vazia e `ECONNREFUSED` com cara de app quebrada; compose cravado **reprova o nó e2e**
+       dentro de um worktree. Se estiver cravado, **isso é uma task**.
      - **Setup de autenticação**, se a aplicação tem login: `e2e.auth` em `config.json`
        (`mode: seed|storageState|bypass|none`, `seedCommand`, `storageStatePath`, `envFile`), com as
        credenciais num `.env.e2e` **gitignored** — nunca no config commitado. **Se a app tem login e

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: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # 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: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-review

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: "8.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-stack-scan

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.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-standards

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.32.0"
+cliVersion: "8.34.2"
 ---
 
 # morph-uiux

package/framework/standards/STANDARDS.json

@@ -2018,6 +2018,36 @@
         "prompt-skeleton": "#section-5-prompt-skeleton"
       },
       "digest": "The decisive rule: a perfect loop has an end frame identical to its start, which is right for a self-playing ambient background and WRONG for scroll scrubbing, because start and end look the same and the page reads as frozen while the user scrolls. Scroll-driven footage needs directional movement via generate_video with an endImage (push-in/dolly is the most reliable, then reveal, pull-back, slow tilt); avoid orbits and any movement that returns to its origin. Client architectural renders are animated with img2vid, never AI-recreated. Human faces repeatedly trip moderation (E005), so crop the face out of frame (neck down, hands, product) and reserve faces for static image generation. Always climb the cost ladder: fast/480p/4s draft to judge framing and movement, 1080p only after approval, then re-extract frames with a bumped cache-bust. Prompts read like director notes with no hype words, and must reserve a calm dark region for the page copy with the subject on the opposite side. Generation is async: generate_video returns a request_id polled via get_video; list_videos reads local history and spends no credits."
+    },
+    {
+      "id": "infrastructure-docker-local-compose-isolation",
+      "name": "local compose isolation",
+      "path": "infrastructure/docker/local-compose-isolation.md",
+      "category": "infrastructure",
+      "subcategory": "docker",
+      "tags": [
+        "infrastructure",
+        "docker"
+      ],
+      "stacks": [
+        "docker"
+      ],
+      "aliases": [
+        "compose isolation",
+        "worktree ports",
+        "container_name",
+        "POSTGRES_PORT",
+        "COMPOSE_PROJECT_NAME",
+        "port block",
+        "local docker compose"
+      ],
+      "anchors": {
+        "layout": "#port-layout-one-contract-everywhere",
+        "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."
     }
   ],
   "sharedAliases": {

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)*