@polymorphism-tech/morph-spec 8.2.0 → 8.3.0

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.2.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-implement
@@ -59,11 +59,14 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    Done quando: [doneCriteria do tasks.json]
 
    Contrato do relatório final:
-   1. ATO FINAL — o seu relatório é a sua ÚLTIMA MENSAGEM DE TEXTO: ela é o
-      valor de retorno desta sessão e chega inteira ao orquestrador. NÃO chame
-      SendMessage: ele gera um evento a mais além da notificação de término,
-      custando um turno inútil ao orquestrador. Escreva o relatório e encerre.
-      Relatório oco, ou sem os 4 itens abaixo, é falha de protocolo.
+   1. GRAVE seu relatório em `.morph/features/{feature}/3-implement/reports/[ID].md`
+      ANTES de encerrar — esse arquivo é o valor de retorno autoritativo desta
+      sessão. A sua última mensagem de texto é cortesia best-effort: pode não
+      chegar inteira ao orquestrador (o evento recebido às vezes é só um
+      idle_notification, sem texto). Ainda assim NÃO chame SendMessage: ele
+      gera um evento a mais além da notificação de término, custando um turno
+      inútil ao orquestrador. Relatório ausente, oco, ou sem os 4 itens abaixo,
+      é falha de protocolo.
    2. NÃO toque em tasks.json, feature.json, state.json nem no board de sessão
       (TaskCreate/TaskUpdate) — todo estado é gravado exclusivamente pelo
       orquestrador.
@@ -74,11 +77,18 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
       commite na branch do worktree como último ato antes do relatório
       e reporte a branch — nunca faça merge.
 
-   Seu relatório final deve conter APENAS: (1) o que foi feito em 2-3 frases,
-   (2) arquivos modificados, (3) problemas encontrados e como foram resolvidos,
-   (4) auto-score 0-10.
+   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,
+   (3) problemas encontrados e como foram resolvidos, (4) auto-score 0-10.
    ```
-   Após receber o retorno: o auto-score é **triagem, não aprovação** — se < 7, re-despache com o feedback específico (ou corrija inline) antes de prosseguir. Em qualquer caso, a task só avança quando `morph-eval` der score ≥ 9 (barra única do MORPH.md §0). Integre o relatório ao recap.md e vá para o passo 7.
+   Após o retorno do dispatch: **leia primeiro** `.morph/features/{feature}/3-implement/reports/[ID].md`
+   — é o valor de retorno autoritativo. Trate a mensagem de texto do sub-agent, se chegou inteira,
+   como um atalho que economiza essa leitura — nunca como a única fonte. Arquivo ausente é falha de
+   protocolo (registre no recap e re-despache/complete a partir do que o sub-agent já fez, se
+   recuperável). O auto-score é **triagem, não aprovação** — se < 7, re-despache com o feedback
+   específico (ou corrija inline) antes de prosseguir. Em qualquer caso, a task só avança quando
+   `morph-eval` der score ≥ 9 (barra única do MORPH.md §0). Integre o relatório ao recap.md e vá
+   para o passo 7.
 
    **Se não — siga para o passo 5.**
 
@@ -136,6 +146,8 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
 
 ## Output esperado
 - Código implementado conforme o standard consultado (direto ou via sub-agent)
+- Quando despachada: `.morph/features/{feature}/3-implement/reports/{taskId}.md` — o relatório
+  autoritativo do sub-agent, canal durável (passo 4)
 - `.morph/features/{feature}/3-implement/recap.md` atualizado com entrada da task concluída
 - `.morph/features/{feature}/2-plan/tasks.json` com status da task atualizado para `done`
 - `.morph/features/{feature}/2-plan/decisions.md` atualizado se houver decisão não trivial

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: "8.2.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-plan

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.2.0"
+cliVersion: "8.3.0"
 ---
 
 # 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.2.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-review
@@ -56,18 +56,22 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          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.
-         Contrato do relatório final — ATO FINAL: o seu relatório é a sua
-         ÚLTIMA MENSAGEM DE TEXTO; ela é o valor de retorno desta sessão e
-         chega inteira ao orquestrador. NÃO chame SendMessage: ele gera um
-         evento a mais além da notificação de término, custando um turno
-         inútil ao orquestrador. Escreva o relatório e encerre.
-         Seu relatório final deve conter: 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.
-         Relatório oco, ou sem esses itens, é falha de protocolo.
+         Contrato do relatório final: GRAVE seu relatório em
+         `.morph/features/{feature}/4-review/evaluator-report.md` ANTES de
+         encerrar — esse arquivo é o valor de retorno autoritativo desta
+         sessão. A sua última mensagem de texto é cortesia best-effort: pode
+         não chegar inteira ao orquestrador (o evento recebido às vezes é só
+         um idle_notification, sem texto). Ainda assim NÃO chame SendMessage:
+         ele gera um evento a mais além da notificação de término, custando
+         um turno inútil ao orquestrador.
+         Seu relatório (no arquivo, e na mensagem final quando ela chega)
+         deve conter: 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. Relatório
+         ausente, oco, ou sem esses itens, é falha de protocolo.
      ```
    - **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 relatório vier oco ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
+   - **Leia primeiro** `.morph/features/{feature}/4-review/evaluator-report.md` — é o valor de retorno autoritativo, não a mensagem de texto do dispatch (que é cortesia, útil só quando chega inteira). Os scores por dimensão e o composto do review-report vêm **desse arquivo**, não da sua auto-avaliação. Se o arquivo vier ausente, oco, ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
@@ -117,7 +121,10 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
 ## Output esperado
-- `.morph/features/{feature}/4-review/review-report.md` com scores e recomendação
+- `.morph/features/{feature}/4-review/evaluator-report.md` — relatório bruto e autoritativo do
+  `morph-evaluator` despachado no passo 4 (canal durável, ver MORPH.md §6)
+- `.morph/features/{feature}/4-review/review-report.md` — síntese do orquestrador a partir do
+  evaluator-report, com scores e recomendação
 - Trace da fase com `phase_summary` preenchido
 - Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo), na forma canônica `{ approved, timestamp, approvedBy }` — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual
 

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.2.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-stack-scan

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: "8.2.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-standards

package/framework/standards/STANDARDS.json

@@ -29,7 +29,7 @@
         "mcp": "#mcp-integration-model-context-protocol",
         "observability": "#observability--opentelemetry"
       },
-      "digest": "Production panorama for MAF agents. Middleware (3 levels) and MCP integration are summarized here and treated canonically in ai-agents-middleware-patterns / ai-agents-mcp-tools / ai-agents-mcp-server. Owns: A2A protocol via Microsoft.Agents.AI.A2A; Redis semantic + HybridCache caching; OpenTelemetry observability with AgentOpenTelemetryConsts.DefaultSourceName; security and production checklists."
+      "digest": "Production panorama for MAF agents. Middleware (3 levels), MCP integration, and observability/OpenTelemetry are summarized here and treated canonically in ai-agents-middleware-patterns / ai-agents-mcp-tools / ai-agents-mcp-server / ai-agents-observability-patterns. Owns: A2A protocol via Microsoft.Agents.AI.A2A; Redis semantic + HybridCache caching; security and production checklists."
     },
     {
       "id": "ai-agents-setup",
@@ -309,6 +309,40 @@
       },
       "digest": "Three middleware levels intercept agent behavior: Agent Run (whole invocation), Function Calling (individual tool calls), IChatClient (raw LLM calls). Register via .AsBuilder().Use(...). Patterns: telemetry, resilience (retry/rate-limit), anti-hallucination (validate tool args before next())."
     },
+    {
+      "id": "ai-agents-observability-patterns",
+      "name": "observability patterns",
+      "path": "ai-agents/observability-patterns.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "observability"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "observability",
+        "opentelemetry",
+        "telemetry",
+        "logging",
+        "tracing",
+        "log investigation",
+        "troubleshooting",
+        "aspire dashboard",
+        "correlation id",
+        "agent observability",
+        "agent telemetry"
+      ],
+      "anchors": {
+        "setup": "#setup--opentelemetry",
+        "enrichment": "#enrichment--o-que-preencher-em-spans-e-logs",
+        "investigation": "#investigação-e-análise--quando-algo-dá-errado"
+      },
+      "digest": "OpenTelemetry setup for MAF agents (AgentOpenTelemetryConsts.DefaultSourceName, traces+metrics+logging). Enrichment: correlation_id propagation across async boundaries, gen_ai.* span attributes, structured ILogger scopes, sensitive-data logging rules. Investigation workflow for production incidents: anchor on correlation_id/time window, drill from root span to children, check metrics before theorizing, reproduce with Debug in staging (never production)."
+    },
     {
       "id": "ai-agents-modalities-vision",
       "name": "modalities vision",
@@ -1756,6 +1790,14 @@
       "ai-agents-production",
       "ai-agents-middleware-patterns"
     ],
+    "agent observability": [
+      "ai-agents-production",
+      "ai-agents-observability-patterns"
+    ],
+    "agent telemetry": [
+      "ai-agents-production",
+      "ai-agents-observability-patterns"
+    ],
     "when not to use workflow": [
       "ai-agents-workflows",
       "ai-agents-sweet-spot"

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

@@ -0,0 +1,156 @@
+# Observability Patterns — OpenTelemetry, enrichment, investigation
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** observability, telemetry, opentelemetry, logging, tracing, log investigation, troubleshooting, aspire dashboard, span, correlation id
+> **Read by Claude in:** implement (wiring telemetry into an agent) and troubleshoot (investigating a production issue)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-07-22.
+
+---
+
+## Por que isso importa
+
+Um agente MAF em produção não é uma função — é uma cadeia (LLM call → tool call → sub-agent → RAG/DB) que pode ter qualquer profundidade. Sem telemetria estruturada, um bug em produção ("o agente respondeu errado", "a automação não disparou") é indistinguível de uma caixa-preta: não dá pra saber qual chamada falhou, quanto cada etapa levou, ou qual tool retornou o quê. Este standard cobre as três partes do problema: **como instrumentar** (setup), **o que registrar** (enrichment) e **como investigar** (análise) — nessa ordem, porque setup sem enrichment produz traces vazios, e enrichment sem prática de investigação não ajuda ninguém no momento do incidente.
+
+---
+
+## Setup — OpenTelemetry
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Trace;
+using OpenTelemetry.Metrics;
+using Microsoft.Agents.AI;
+
+// Habilitar em agents individuais
+agent.WithOpenTelemetry();
+
+// Program.cs — setup completo
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing =>
+    {
+        tracing.AddSource(AgentOpenTelemetryConsts.DefaultSourceName);   // MAF 1.0 GA source
+        tracing.AddSource(builder.Environment.ApplicationName);          // seus spans customizados (ver Enrichment)
+        tracing.AddAspNetCoreInstrumentation();
+        tracing.AddHttpClientInstrumentation();
+        tracing.AddOtlpExporter();
+    })
+    .WithMetrics(metrics =>
+    {
+        metrics.AddMeter(AgentOpenTelemetryConsts.DefaultSourceName);
+        metrics.AddAspNetCoreInstrumentation();
+        metrics.AddHttpClientInstrumentation();
+        metrics.AddRuntimeInstrumentation();
+    });
+
+builder.Logging.AddOpenTelemetry(logging =>
+{
+    logging.IncludeFormattedMessage = true;
+    logging.IncludeScopes = true;           // necessário para correlação — ver Enrichment
+    logging.AddOtlpExporter();
+});
+```
+
+> **Source name:** sempre `AgentOpenTelemetryConsts.DefaultSourceName` de `Microsoft.Agents.AI`.
+> **NÃO usar** o source string `"Experimental.[pacote-antigo].*"` — pertence à família `Microsoft.Extensions.AI` 9.x, incompatível com MAF 1.0 GA.
+> **Produção:** desabilite dados sensíveis — `EnableSensitiveTelemetryData = false` no agent — para não vazar prompt/response completos no backend de export.
+
+### Aspire Dashboard (dev/local)
+
+Visualiza em tempo real: fluxo completo de conversas entre agents, ciclos de tool call (Model → Tool → Model), token usage e latência por chamada, error traces e retry patterns. Para ambientes hospedados (Coolify), exporte via OTLP para o backend de observability do projeto — ver `infrastructure-docker-coolify-deploy` para o setup de Serilog/JSON console log que alimenta o mesmo pipeline de agregação.
+
+---
+
+## Enrichment — o que preencher em spans e logs
+
+Setup sem enrichment produz traces tecnicamente corretos mas operacionalmente inúteis — você vê "uma chamada ao LLM aconteceu", não "por que ela demorou 8s" ou "qual feature/task gerou essa chamada". Preencha sempre:
+
+### Correlação entre trace, feature e requisição
+
+```csharp
+using var activity = Activity.Current;
+activity?.SetTag("morph.feature", featureName);
+activity?.SetTag("morph.task_id", taskId);
+activity?.SetTag("morph.correlation_id", correlationId);   // mesmo ID em toda a cadeia de uma requisição de usuário
+```
+
+Sem um `correlation_id` propagado manualmente através de chamadas assíncronas/filas (Hangfire, background jobs), você não consegue religar "o usuário reclamou às 14:32" a um trace específico — o `TraceId` do OpenTelemetry sozinho não sobrevive a um boundary de fila.
+
+### Atributos de custo e uso do modelo
+
+```csharp
+activity?.SetTag("gen_ai.request.model", modelAlias);       // alias do Model Registry, nunca o nome hardcoded
+activity?.SetTag("gen_ai.usage.prompt_tokens", usage.PromptTokens);
+activity?.SetTag("gen_ai.usage.completion_tokens", usage.CompletionTokens);
+activity?.SetTag("gen_ai.response.finish_reason", finishReason);
+```
+
+Nomeação `gen_ai.*` segue a convenção semântica OpenTelemetry para GenAI — mantém compatibilidade se o backend de observability tiver dashboards prontos para essa convenção.
+
+### Logging estruturado com `ILogger` — sempre com scope
+
+```csharp
+using (_logger.BeginScope(new Dictionary<string, object>
+{
+    ["FeatureId"] = featureName,
+    ["TaskId"] = taskId,
+    ["AgentId"] = agentPersonaId
+}))
+{
+    _logger.LogInformation("Tool call {ToolName} started with args {Args}", toolName, args);
+    // ... chamada ...
+    _logger.LogInformation("Tool call {ToolName} completed in {ElapsedMs}ms", toolName, elapsed);
+}
+```
+
+- **Sempre** parâmetros nomeados no template (`{ToolName}`, não string interpolada) — permite querying estruturado no backend em vez de grep de texto livre.
+- **Nunca** logar o conteúdo completo do prompt/response em `Information` — isso é PII/dado sensível do cliente por padrão. Logar em `Debug` apenas, e só se `EnableSensitiveTelemetryData` estiver habilitado explicitamente para o ambiente.
+- **Nível de log por tipo de evento:** `Information` para início/fim de tool call e decisões do agent; `Warning` para retry/fallback de provider; `Error` apenas para falhas que geram resposta degradada ao usuário (não para toda exceção capturada e tratada).
+
+---
+
+## Investigação e análise — quando algo dá errado
+
+Workflow para diagnosticar um incidente relatado ("o agente X respondeu errado/lento/nada às HH:MM"):
+
+1. **Ancore no correlation_id ou janela de tempo.** Se o relato tem um identificador (número de WhatsApp, feature, conversationId), busque por ele nos atributos (`morph.correlation_id`, `gen_ai.*`) — não pelo texto do log. Sem identificador, restrinja pela janela de tempo + `morph.feature`/`AgentId` antes de olhar qualquer trace individual.
+2. **Suba do trace raiz para os spans filhos.** O span raiz mostra a duração total; os filhos (`Function Calling`, `IChatClient`) mostram onde o tempo/erro realmente está. Não assuma — meça. Um "agente lento" é quase sempre UM tool call específico (chamada de API externa, query sem índice), não o LLM.
+3. **Correlacione com métricas antes de teorizar.** Confira a tabela "What to Monitor" abaixo pelo período do incidente — um pico de `tool call failure rate` ou `token usage` aponta a causa mais rápido que ler traces individuais um a um.
+4. **Reproduza com Debug ligado, nunca em produção.** Se a causa não estiver clara nos atributos estruturados, habilite `Debug` (com dados sensíveis, se necessário) num ambiente de staging com o mesmo input — nunca habilite log de prompt/response completo em produção para investigar.
+5. **Documente a causa raiz em `decisions.md`** se a investigação levar a uma mudança de arquitetura (novo middleware de retry, novo timeout, novo cache) — não só no commit message.
+
+### What to Monitor
+
+| Metric | Purpose | Alert Threshold |
+|--------|---------|------------------|
+| Token usage per request | Cost control | > 10K tokens/request |
+| Latency per agent call | Performance | > 5s for simple tasks |
+| Tool call failure rate | Reliability | > 5% failures |
+| Cache hit rate | Cost optimization | < 50% (tune strategy) |
+| Model drift | Quality | Evaluation score drop > 10% |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] OpenTelemetry configurado com `AgentOpenTelemetryConsts.DefaultSourceName` (traces + metrics + logging)
+- [ ] `EnableSensitiveTelemetryData = false` fora de dev/staging
+- [ ] Todo tool call relevante tem `correlation_id` propagado manualmente através de boundaries assíncronos (filas, background jobs)
+- [ ] Logging via `ILogger` com `BeginScope` estruturado, nunca string interpolada em templates de log
+- [ ] Nenhum log em `Information`/produção contém prompt/response completo
+- [ ] Alertas configurados para os thresholds da tabela "What to Monitor" relevantes ao projeto
+
+---
+
+## References
+
+- `ai-agents-production` — panorama de produção; esta seção era resumida lá, tratamento canônico agora aqui
+- `ai-agents-middleware-patterns` — middleware de telemetria no nível `IChatClient` (`TelemetryMiddleware`)
+- `infrastructure-docker-coolify-deploy` — Serilog/JSON console log para o pipeline de agregação em produção
+- [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+- [Agent Observability](https://learn.microsoft.com/agent-framework/user-guide/observability/)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/observability-patterns.md v1.0 (2026-07-22)*

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

@@ -179,54 +179,9 @@ public async Task<WeatherResponse> GetWeatherAsync(
 
 ## Observability / OpenTelemetry
 
-```csharp
-using OpenTelemetry;
-using OpenTelemetry.Trace;
-using OpenTelemetry.Metrics;
-using Microsoft.Agents.AI;
-
-// Enable on individual agents
-agent.WithOpenTelemetry();
-
-// Program.cs — full setup
-builder.Services.AddOpenTelemetry()
-    .WithTracing(tracing =>
-    {
-        tracing.AddSource(AgentOpenTelemetryConsts.DefaultSourceName);   // MAF 1.0 GA source
-        tracing.AddSource(builder.Environment.ApplicationName);
-        tracing.AddAspNetCoreInstrumentation();
-        tracing.AddHttpClientInstrumentation();
-        tracing.AddOtlpExporter();
-    })
-    .WithMetrics(metrics =>
-    {
-        metrics.AddMeter(AgentOpenTelemetryConsts.DefaultSourceName);    // MAF 1.0 GA meter
-        metrics.AddAspNetCoreInstrumentation();
-        metrics.AddHttpClientInstrumentation();
-        metrics.AddRuntimeInstrumentation();
-    });
-```
-
-> **Source name:** sempre `AgentOpenTelemetryConsts.DefaultSourceName` de `Microsoft.Agents.AI`.
-> **NÃO usar** o source string `"Experimental.[pacote-antigo].*"` — pertence à família `Microsoft.Extensions.AI 9.x`, incompatível com MAF 1.0 GA.
-
-### Aspire Dashboard
-
-Visualiza traces de agents incluindo:
-- Fluxo completo de conversas entre agents
-- Tool call cycles (Model → Tool → Model)
-- Token usage e latência por chamada
-- Error traces e retry patterns
-
-### What to Monitor
+Setup, enrichment (span attributes, correlation IDs, structured logging) e o workflow de investigação/análise de logs em produção têm **tratamento canônico** em **`ai-agents-observability-patterns`**. Não duplicado aqui.
 
-| Metric | Purpose | Alert Threshold |
-|--------|---------|----------------|
-| Token usage per request | Cost control | > 10K tokens/request |
-| Latency per agent call | Performance | > 5s for simple tasks |
-| Tool call failure rate | Reliability | > 5% failures |
-| Cache hit rate | Cost optimization | < 50% (tune strategy) |
-| Model drift | Quality | Evaluation score drop > 10% |
+> Em produção: source name sempre `AgentOpenTelemetryConsts.DefaultSourceName`; `EnableSensitiveTelemetryData = false` fora de dev/staging. Ver `ai-agents-observability-patterns` para o setup completo, o que preencher em cada span/log, e o workflow de investigação quando um incidente for reportado.
 
 ---
 
@@ -262,6 +217,7 @@ Visualiza traces de agents incluindo:
 - `ai-agents-sweet-spot` — decisão de arquitetura antes de middleware
 - `ai-agents-providers-model-registry` — Model Registry para `_modelRegistry.GetChatClient(...)`
 - `ai-agents-middleware-patterns` — **tratamento canônico** de middleware (código dos 3 níveis, telemetria, resilência, anti-hallucination)
+- `ai-agents-observability-patterns` — **tratamento canônico** de observability (setup OpenTelemetry, enrichment de spans/logs, workflow de investigação)
 - `ai-agents-mcp-tools` — agente MAF consumindo MCP servers externos
 - `ai-agents-mcp-server` — projeto expondo capacidades como MCP server
 - `ai-agents-rag-custom-pgvector` — implementação completa de busca semântica (referida em Caching)

package/framework/templates/REGISTRY.json

@@ -109,55 +109,6 @@
       "technology": "handlebars",
       "validatePlaceholders": true
     },
-    {
-      "id": "context",
-      "kind": "template",
-      "name": "Project Context",
-      "path": "context/CONTEXT.md",
-      "location": "framework",
-      "category": "context",
-      "phase": "proposal",
-      "required": false,
-      "description": "Project-level context with tech stack, active features, agents, standards",
-      "outputName": "CONTEXT.md",
-      "placeholders": [
-        "AGENT_COUNT",
-        "AGENT_TEAMS_DISPLAY_MODE",
-        "AGENT_TEAMS_THRESHOLDS",
-        "APP_INSIGHTS",
-        "AZURE_LOCATION",
-        "CONTAINER_ENV",
-        "COOLIFY_APP_URL",
-        "COOLIFY_SERVER",
-        "DEVOPS_AREA_PATH",
-        "DEVOPS_BUILD_PIPELINE",
-        "DEVOPS_ORG",
-        "DEVOPS_PROJECT",
-        "DEVOPS_RELEASE_PIPELINE",
-        "DEVOPS_WIKI_NAME",
-        "DOTNET_VERSION",
-        "EF_VERSION",
-        "INFERRED_STANDARDS",
-        "MORPH_VERSION",
-        "NEON_PROJECT_ID",
-        "NEON_REGION",
-        "NEXTJS_VERSION",
-        "OPENAI_MODEL",
-        "PROJECT_DESCRIPTION",
-        "PROJECT_NAME",
-        "PROJECT_TYPE",
-        "REPOSITORY_URL",
-        "SQL_DATABASE",
-        "SQL_SERVER",
-        "TIMESTAMP",
-        "UI_LIBRARY"
-      ],
-      "stackSpecific": false,
-      "engine": "handlebars",
-      "deprecated": false,
-      "technology": "handlebars",
-      "validatePlaceholders": true
-    },
     {
       "id": "architecture",
       "kind": "template",
@@ -176,50 +127,6 @@
       "technology": "handlebars",
       "validatePlaceholders": true
     },
-    {
-      "id": "context-feature",
-      "kind": "template",
-      "name": "Feature Context",
-      "path": "context/CONTEXT-FEATURE.md",
-      "location": "framework",
-      "category": "context",
-      "phase": "proposal",
-      "required": false,
-      "description": "Feature-level context with progress, agents, tasks, decisions, validations",
-      "outputName": "CONTEXT-FEATURE.md",
-      "placeholders": [
-        "ACTIVE_AGENTS_COUNT",
-        "AGENT_TEAMS_DECISION",
-        "COMPLEXITY",
-        "CONTRACTS_PATH",
-        "CURRENT_TASK",
-        "DECISIONS_PATH",
-        "DESCRIPTION",
-        "FEATURE_ID",
-        "FEATURE_NAME",
-        "MORPH_VERSION",
-        "PHASE",
-        "PHASE_DESCRIPTION",
-        "PROPOSAL_PATH",
-        "RECAP_PATH",
-        "SPEC_PATH",
-        "STATUS",
-        "TASKS_BLOCKED",
-        "TASKS_COMPLETED",
-        "TASKS_IN_PROGRESS",
-        "TASKS_PATH",
-        "TASKS_PROGRESS",
-        "TASKS_TOTAL",
-        "TEAM_LEAD",
-        "TIMESTAMP",
-        "VALIDATION_TIMESTAMP"
-      ],
-      "stackSpecific": false,
-      "engine": "handlebars",
-      "deprecated": false,
-      "technology": "handlebars",
-      "validatePlaceholders": true
-    },
     {
       "id": "spec-examples",
       "kind": "template",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/observability/telemetry.js

@@ -0,0 +1,75 @@
+/**
+ * `morph-spec telemetry [--json] [--feature <name>] [--limit <n>]`
+ *
+ * The reader surface over the harness event stream (.morph/logs/events.jsonl,
+ * written by the telemetry-log hook). Reconstructs the whole execution path of
+ * an NLH session: top skills, personas dispatched, standards (knowledge base)
+ * read, the tool mix, and the recent prompts (user + sub-agent).
+ *
+ * Read-only, always exits 0 (fail-open — an empty stream is an answer).
+ */
+
+import chalk from 'chalk';
+import { loadTelemetry, aggregateTelemetry } from '../../lib/telemetry/telemetry-reader.js';
+
+// The knowledge-base count reflects EXPLICIT reads only. The core standards
+// load via @-refs in rules (Layer 0/1 auto-load) — those are injected by
+// Claude Code's rules system, not via the Read tool, so no hook ever sees them.
+// A low count here means "few on-demand reads", NOT "standards barely used".
+const STANDARDS_CAVEAT =
+  'Só reads explícitos (via Read) são observáveis; standards auto-carregados por @-ref nas rules (Layer 0/1) não passam por tool call e ficam invisíveis aqui.';
+
+function section(title, rows, fmt) {
+  if (!rows.length) return;
+  console.log('\n' + chalk.white.bold(title));
+  for (const r of rows) console.log('  ' + fmt(r));
+}
+
+/**
+ * @param {{ json?: boolean, feature?: string, limit?: number, cwd?: string }} [options]
+ */
+export function telemetryCommand(options = {}) {
+  const events = loadTelemetry(options.cwd || process.cwd());
+  const summary = aggregateTelemetry(events, { feature: options.feature });
+
+  if (options.json) {
+    console.log(JSON.stringify({ ...summary, notes: { standards: STANDARDS_CAVEAT } }));
+    process.exit(0);
+  }
+
+  if (summary.total === 0) {
+    const scope = options.feature ? ` para a feature "${options.feature}"` : '';
+    console.log(chalk.gray(`Telemetria vazia${scope} — nenhum evento capturado ainda em .morph/logs/events.jsonl.`));
+    process.exit(0);
+  }
+
+  const scope = options.feature ? chalk.cyan(` · feature ${options.feature}`) : '';
+  console.log(chalk.white.bold(`Telemetria do harness — ${summary.total} eventos${scope}`));
+  if (summary.features.length) {
+    console.log(chalk.gray(`Features: ${summary.features.join(', ')}`));
+  }
+
+  section('Skills', summary.skills, s => `${chalk.green(s.name.padEnd(24))} ${s.count}`);
+  section('Personas despachadas', summary.personas, p => `${chalk.magenta(p.name.padEnd(24))} ${p.count}`);
+  section('Base de conhecimento (standards lidos explicitamente)', summary.standards,
+    s => `${chalk.yellow(String(s.count).padStart(3))}×  ${s.path}`);
+  if (summary.standards.length || summary.tools.some(t => t.name === 'Read')) {
+    console.log(chalk.gray(`  ⚠ ${STANDARDS_CAVEAT}`));
+  }
+  section('Mix de tools', summary.tools, t => `${t.name.padEnd(16)} ${t.count}`);
+
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 10;
+  const prompts = summary.prompts.slice(-limit);
+  if (prompts.length) {
+    console.log('\n' + chalk.white.bold(`Prompts (últimos ${prompts.length})`));
+    for (const p of prompts) {
+      const tag = p.source === 'user' ? chalk.blue('user ') : chalk.magenta('agent');
+      const where = p.feature ? chalk.gray(` [${p.feature}/${p.phase || '-'}]`) : '';
+      const oneLine = String(p.text || '').replace(/\s+/g, ' ').trim();
+      const preview = oneLine.length > 120 ? oneLine.slice(0, 117) + '...' : oneLine;
+      console.log(`  ${tag}${where} ${preview}`);
+    }
+  }
+
+  process.exit(0);
+}