@polymorphism-tech/morph-spec 8.2.1 → 8.4.0

package/framework/hooks/claude-code/core/state-sync.js

@@ -66,8 +66,9 @@ function registerFeatureIfMissing(state, featureName) {
   if (!state.features) state.features = {};
   if (state.features[featureName]) return false;
 
-  // Canonical object-form gates (incl. optional uiux) — no boolean drift.
-  state.features[featureName] = createDefaultFeature();
+  // Canonical object-form gates (incl. optional uiux) + stamped identity
+  // (name=slug, workType, createdAt) — no anonymous shell, no boolean drift.
+  state.features[featureName] = createDefaultFeature(featureName);
   return true;
 }
 
@@ -114,6 +115,15 @@ function gateFromQuestion(question) {
   return null;
 }
 
+// Gate monotonicity — mirror of src/core/state/gate-order.js (hooks are
+// installed standalone and cannot import from src/). Keep in sync:
+// proposal → plan → review; uiux requires proposal.
+const GATE_PREREQ = { proposal: [], uiux: ['proposal'], plan: ['proposal'], review: ['plan'] };
+function unmetGatePrereqs(gate, gates) {
+  const isApproved = (g) => gates?.[g]?.approved === true || gates?.[g] === true;
+  return (GATE_PREREQ[gate] || []).filter((p) => !isApproved(p));
+}
+
 function handleWriteEdit(input, cwd) {
   const filePath = input.tool_input?.file_path;
   const featureName = extractFeatureName(filePath);
@@ -139,23 +149,38 @@ function handleWriteEdit(input, cwd) {
 
 function handleAskUserQuestion(input, cwd) {
   const answers = input.tool_response?.answers ?? input.tool_response?.responses ?? {};
-  if (typeof answers !== 'object' || answers === null) return false;
+  if (typeof answers !== 'object' || answers === null) return null;
 
   const state = loadState(cwd);
-  if (!state) return false;
+  if (!state) return null;
 
   const featureName = findActiveFeature(state);
-  if (!featureName) return false;
+  if (!featureName) return null;
 
+  const warnings = [];
   for (const [question, answer] of Object.entries(answers)) {
     if (!isApprovalAnswer(answer)) continue;
     const gate = gateFromQuestion(question);
     if (!gate) continue;
 
-    const existing = state.features[featureName].approvalGates?.[gate];
+    const gates = state.features[featureName].approvalGates;
+    const existing = gates?.[gate];
     const alreadyApproved = existing === true || existing?.approved === true;
     if (alreadyApproved) continue;
 
+    // Gate monotonicity: fail-open. The human said "aprovado", so we DO approve
+    // (never block a human in the loop), but if a predecessor gate is still
+    // pending we surface a non-blocking warning — the CLI `morph-spec approve`
+    // hard-refuses the same shape; here we alert so the operator can reconcile.
+    const unmet = unmetGatePrereqs(gate, gates);
+    if (unmet.length) {
+      warnings.push(
+        `⚠️ [morph-spec] GATE FORA DE ORDEM — o Gate "${gate}" de "${featureName}" foi aprovado, ` +
+        `mas o(s) gate(s) anterior(es) ${unmet.join(', ')} não estão aprovados (ordem: ${unmet.join(' → ')} → ${gate}). ` +
+        `Aprove os gates anteriores ou reveja com 'morph-spec doctor'.`
+      );
+    }
+
     // An "aprovado" answer to AskUserQuestion is a human approving in the loop.
     // Route through the shared canonical gate writer so the hook and the CLI
     // (`morph-spec approve`) produce one consistent shape
@@ -163,7 +188,7 @@ function handleAskUserQuestion(input, cwd) {
     // and a manual approval stays distinguishable from a policy auto-approval.
     setGateApproved(featureName, gate, { approvedBy: 'manual' }, cwd);
   }
-  return true;
+  return warnings.length ? warnings.join('\n') : null;
 }
 
 async function main() {
@@ -176,17 +201,24 @@ async function main() {
   const input = readStdin();
   const toolName = input.tool_name;
 
+  let warning = null;
   try {
     if (toolName === 'Write' || toolName === 'Edit') {
       handleWriteEdit(input, cwd);
     } else if (toolName === 'AskUserQuestion') {
-      handleAskUserQuestion(input, cwd);
+      warning = handleAskUserQuestion(input, cwd);
     }
   } catch {
     // fail-open
   }
 
-  exit();
+  // A non-blocking order-violation warning is surfaced as injected context
+  // (hookSpecificOutput.additionalContext); everything else exits silently.
+  if (warning) {
+    exit({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warning } });
+  } else {
+    exit();
+  }
 }
 
 main().catch(() => exit());

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * Telemetry Hook: harness execution-path capture
+ *
+ * Events: PostToolUse (all tools) + UserPromptSubmit
+ *
+ * morph-spec is a Natural Language Harness: there is no central runtime to
+ * instrument — Claude Code executes the skills and sub-agents. The only
+ * vantage points are hooks. This one is the generic capture point: every tool
+ * call and every user prompt is appended (one JSON line) to
+ * .morph/logs/events.jsonl, from which `morph-spec telemetry` reconstructs the
+ * whole path — which skills ran, which personas were dispatched (with their
+ * prompts), which standards/knowledge-base files were read.
+ *
+ * Correlation is by an EXPLICIT key (feature + phase) written into each event,
+ * not by ambient span context — hooks fire as separate node processes with no
+ * shared trace context (the enrichment lesson from the observability standard:
+ * propagate a correlation key, a TraceId does not survive the boundary).
+ *
+ * SILENT: never blocks, never injects context — only appends. Fail-open on any
+ * error (exit 0). Only active inside a morph project (stateExists gate).
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
+import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
+import { pass } from '../../shared/hook-response.js';
+
+function normalize(p) {
+  return (p || '').replace(/\\/g, '/');
+}
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const cwd = process.cwd();
+
+  // Correlation key: active feature + its phase (explicit, not ambient).
+  // NOTE (perf): getActiveFeature → loadState hydrates every .morph/features/*/
+  // feature.json, so enrichment is O(active-feature-count) per tool call. That
+  // is fine for realistic projects (archive removes finished features, so the
+  // dir holds only the few in-flight ones) but would grow on a project that
+  // keeps many un-archived features. If that ever bites, resolve the active
+  // feature from the thin state.json index alone. Kept accurate-over-cheap for
+  // now because phase is not stored in feature.json — it needs derivation.
+  let feature = null;
+  let phase = null;
+  try {
+    const active = getActiveFeature(cwd);
+    if (active) {
+      feature = active.name;
+      phase = active.feature?.phase || derivePhaseForFeature(active.name, cwd);
+    }
+  } catch {
+    // enrichment is best-effort — a missing feature never blocks capture
+  }
+
+  let event;
+
+  // UserPromptSubmit carries the user's prompt and no tool_name.
+  if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
+    event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: payload.prompt || '' };
+  } else {
+    const tool = payload.tool_name;
+    if (!tool) pass();
+    const input = payload.tool_input || {};
+    event = { event: 'PostToolUse', tool };
+
+    if (tool === 'Skill') {
+      event.skill = input.skill || '';
+    } else if (tool === 'Agent' || tool === 'Task') {
+      event.persona = input.subagent_type || '';
+      if (input.description) event.desc = input.description;
+      event.prompt = input.prompt || '';
+    } else if (tool === 'Read') {
+      event.target = normalize(input.file_path || input.path);
+      if (/\/standards\//.test(event.target)) event.kind = 'standard';
+    } else if (tool === 'Bash') {
+      event.command = input.command || '';
+    } else if (tool === 'Write' || tool === 'Edit') {
+      event.target = normalize(input.file_path || input.path);
+    } else {
+      // Every other tool still counts toward "the whole path" — record a
+      // compact target so Grep/Glob/WebFetch bursts remain distinguishable.
+      const target = input.file_path || input.path || input.pattern || input.query || input.url || '';
+      if (target) event.target = normalize(String(target));
+    }
+  }
+
+  event.feature = feature;
+  event.phase = phase;
+
+  appendTelemetryEvent(event, cwd);
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/shared/state-writer.js

@@ -91,7 +91,7 @@ export function persistFeature(featureName, feature, projectPath) {
  */
 export function setGateApproved(featureName, gate, meta = {}, projectPath) {
   try {
-    const feature = readFeatureFile(featureName, projectPath) || createDefaultFeature();
+    const feature = readFeatureFile(featureName, projectPath) || createDefaultFeature(featureName);
     const now = new Date().toISOString();
     feature.approvalGates = feature.approvalGates || {};
     feature.approvalGates[gate] = {
@@ -106,11 +106,22 @@ export function setGateApproved(featureName, gate, meta = {}, projectPath) {
   }
 }
 
-/** Default feature shape (canonical object-form gates, incl. optional uiux). */
-export function createDefaultFeature() {
+/**
+ * Default feature shape (canonical object-form gates, incl. optional uiux).
+ * Stamps identity — name (the slug), workType, createdAt — so the implicit
+ * birth path (state-sync registering a feature on the first Write) never
+ * produces an anonymous {status,updatedAt} shell. `description` stays absent
+ * (a hook can't invent it); `list`/`doctor` flag its absence. Mirrors the CLI
+ * createFeature's stamping.
+ *
+ * @param {string} [featureName] - the feature slug, stamped as `name`
+ */
+export function createDefaultFeature(featureName) {
   const now = new Date().toISOString();
   return {
+    ...(featureName ? { name: featureName } : {}),
     status: 'in_progress',
+    workType: 'feature',
     createdAt: now,
     updatedAt: now,
     approvalGates: {

package/framework/hooks/shared/telemetry-logger.js

@@ -0,0 +1,75 @@
+/**
+ * Telemetry Logger — append-only harness event stream
+ *
+ * Writes one JSON line per event to .morph/logs/events.jsonl. This is the sink
+ * for the `telemetry-log` hook, which fires on every tool call (PostToolUse,
+ * all tools) and on every user prompt (UserPromptSubmit) — the only vantage
+ * points an NLH exposes. The whole execution path (skills, sub-agent dispatch,
+ * knowledge-base reads, prompts) is reconstructable by reading this file.
+ *
+ * Design constraints (same discipline as activity-logger, plus one):
+ * - Synchronous only (hooks run in process, no async overhead)
+ * - Fail-silent (never throws — hooks must not be blocked by the logger)
+ * - APPEND-ONLY: one `appendFileSync` line per event, O(1) per call. The
+ *   read-modify-write of a whole JSON doc (activity-logger) is O(n²) across a
+ *   session and blows the ≤5ms budget once tool calls number in the hundreds.
+ * - Windows-safe paths via path.join
+ */
+
+import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+const LOGS_DIR = '.morph/logs';
+export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
+
+function getEventsPath(projectPath) {
+  return join(projectPath || process.cwd(), EVENTS_FILE);
+}
+
+/**
+ * Append a single telemetry event as one JSON line.
+ * Stamps an ISO `ts` when the caller omits one.
+ *
+ * @param {Object} event - Event payload (tool, skill/persona/target/prompt, feature, phase…)
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function appendTelemetryEvent(event, projectPath) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    const dir = dirname(eventsPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    const stamped = { ts: event?.ts || new Date().toISOString(), ...event };
+    appendFileSync(eventsPath, JSON.stringify(stamped) + '\n', 'utf-8');
+  } catch {
+    // Fail-silent — never block hooks
+  }
+}
+
+/**
+ * Read the full event stream back into an array. A corrupt/truncated line
+ * (e.g. a killed process mid-write) is skipped, not fatal.
+ *
+ * @param {string} [projectPath]
+ * @returns {Object[]} events in write order (may be empty)
+ */
+export function readTelemetryEvents(projectPath) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return [];
+    const raw = readFileSync(eventsPath, 'utf-8');
+    const events = [];
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        events.push(JSON.parse(trimmed));
+      } catch {
+        // skip a single corrupt line — don't lose the whole stream
+      }
+    }
+    return events;
+  } catch {
+    return [];
+  }
+}

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

@@ -20,6 +20,7 @@ stacks:
 @.morph/framework/standards/ai-agents/prompts-in-db.md
 @.morph/framework/standards/ai-agents/rag-custom-pgvector.md
 @.morph/framework/standards/ai-agents/middleware-patterns.md
+@.morph/framework/standards/ai-agents/observability-patterns.md
 @.morph/framework/standards/ai-agents/workflows.md
 @.morph/framework/standards/ai-agents/production.md
 

package/framework/schemas/feature.schema.json

@@ -5,10 +5,18 @@
   "type": "object",
   "required": ["status", "approvalGates"],
   "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable feature name, stamped at birth by `morph-spec create` (defaults to the slug) and by the state-sync hook's implicit registration. Kept out of the schema's `required` array — adding it there would invalidate every feature.json that predates identity stamping; instead `create` enforces it at birth and `morph-spec doctor`/`list` flag its absence leniently."
+    },
+    "description": {
+      "type": "string",
+      "description": "What/why of the feature. The one identity field a human must supply — `morph-spec create` refuses a new feature without it (--description, or --request which seeds it). Absent on features born via the implicit hook path; surfaced as a warning by `doctor`/`list`, never a hard read-time rejection (see name)."
+    },
     "status": {
       "type": "string",
-      "enum": ["draft", "in_progress", "completed"],
-      "description": "Feature lifecycle status. `completed` is stamped by `morph-spec archive` together with archivedAt."
+      "enum": ["draft", "in_progress", "completed", "abandoned"],
+      "description": "Feature lifecycle status. `completed` is stamped by `morph-spec archive` together with archivedAt. `abandoned` is stamped by `morph-spec delete --archive` together with abandonedAt (dead scaffold / killed draft, kept in .morph/archive)."
     },
     "createdAt": { "type": "string", "format": "date-time" },
     "updatedAt": {
@@ -21,6 +29,11 @@
       "format": "date-time",
       "description": "Stamped by `morph-spec archive`."
     },
+    "abandonedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Stamped by `morph-spec delete --archive` when a dead/abandoned feature is moved to .morph/archive."
+    },
     "approvalGates": {
       "type": "object",
       "description": "One entry per gate. Written ONLY by `morph-spec approve`/`advance` (approvedBy: \"auto\") or the state-sync hook on a human \"aprovado\" answer (approvedBy: \"manual\").",
@@ -195,12 +208,7 @@
       },
       "additionalProperties": true
     },
-    "activeAgents": { "type": "array", "items": { "type": "string" } },
     "checkpoints": { "type": "array" },
-    "dispatchLog": {
-      "type": "array",
-      "description": "Dispatch events (capped at 50). Entries: { timestamp, phase, mode, agents: [{ id, subagentType, group, tasks }] }."
-    },
     "trustConfig": { "type": "object" },
     "contextBundles": { "type": "array" },
     "fileChanges": { "type": "array" },

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.2.1"
+cliVersion: "8.4.0"
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.2.1"
+cliVersion: "8.4.0"
 ---
 
 # migrate-lp-to-umbraco

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

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.2.1"
+cliVersion: "8.4.0"
 ---
 
 # morph-apply

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.2.1"
+cliVersion: "8.4.0"
 ---
 
 # 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.2.1"
+cliVersion: "8.4.0"
 ---
 
 # 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.2.1"
+cliVersion: "8.4.0"
 ---
 
 # morph-hotfix
@@ -28,10 +28,10 @@ Resolver uma queda ou bug crítico de produção o mais rápido possível — pr
 ### 1. Nascimento da feature
 
 ```
-morph-spec create {feature} --type hotfix
+morph-spec create {feature} --type hotfix --description "<o incidente: o que quebrou / sintoma>"
 ```
 
-Carimba os gates `proposal` e `plan` como `approvedBy: "policy:hotfix"` e cria as pastas `0-proposal/`, `2-plan/`, `3-implement/` num passo só — a feature já nasce em `implement` (fase derivada é gate-aware). Se a feature já existe, siga adiante sem recriar.
+Carimba `name` (o slug) + `description` (obrigatória no nascimento — descreva o incidente) e os gates `proposal`/`plan` como `approvedBy: "policy:hotfix"`, e cria as pastas `0-proposal/`, `2-plan/`, `3-implement/` num passo só — a feature já nasce em `implement` (fase derivada é gate-aware). Se a feature já existe, siga adiante sem recriar.
 
 ### 2. Scout — mapa do território (obrigatório)
 

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.1"
+cliVersion: "8.4.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: "8.2.1"
+cliVersion: "8.4.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.1"
+cliVersion: "8.4.0"
 ---
 
 # morph-proposal
@@ -38,10 +38,10 @@ Antes de qualquer trabalho de negócio, classifique o pedido. Se `{feature-name}
 morph-spec create {feature-name} --request "<pedido do usuário>"
 ```
 
-(ou `--type <tipo>` diretamente quando o tipo é óbvio pelo pedido — ex.: o usuário já diz "isso é um hotfix").
+(ou `--type <tipo> --description "<o quê/porquê>"` diretamente quando o tipo é óbvio pelo pedido — ex.: o usuário já diz "isso é um hotfix"). O `--request` **serve de semente da descrição**: toda feature nasce com `name` (o slug) e `description` (obrigatória) carimbados. Sem `--request` nem `--description`, o `create` recusa — nada de scaffolds anônimos.
 
 - **Classificação `high` confidence** — a feature nasce com o `workType` decidido pelo detector determinístico (keywords: `hotfix` — "produção caiu/urgente/incident/p0"; `bug` — "bug/corrigir/exception/regressão"; `chore` — "typo/rename/bump/config/docs/cleanup"). Prossiga para o branch correspondente abaixo.
-- **Exit 2** (empate `tie` ou nenhum sinal `none`) — o comando sai sem criar a feature e imprime `{ needsDecision, candidates, matched }`. **Você é o roteador**: decida o tipo entre os candidatos e re-rode com `morph-spec create {feature-name} --type <tipo>`. Só use `AskUserQuestion` para o usuário quando o pedido for genuinamente indeterminado — a maioria dos empates o roteador resolve sozinho pelo contexto da conversa.
+- **Exit 2** (empate `tie` ou nenhum sinal `none`) — o comando sai sem criar a feature e imprime `{ needsDecision, candidates, matched }`. **Você é o roteador**: decida o tipo entre os candidatos e re-rode com `morph-spec create {feature-name} --type <tipo> --request "<pedido do usuário>"` (o `--request` re-passado carimba a descrição). Só use `AskUserQuestion` para o usuário quando o pedido for genuinamente indeterminado — a maioria dos empates o roteador resolve sozinho pelo contexto da conversa.
 
 **Branches por tipo** (dimensionamento completo em `MORPH.md` §2.1):
 
@@ -55,7 +55,7 @@ morph-spec create {feature-name} --request "<pedido do usuário>"
 - Se argumento ausente: perguntar via `AskUserQuestion` (1 pergunta, header "Feature").
 - Verificar `.morph/features/{feature-name}/`:
   - Se `0-proposal/proposal.md` existe e tem conteúdo: pular para passo 3.
-  - Caso contrário: rode `morph-spec create {feature-name}` — cria `.morph/features/{feature-name}/0-proposal/` e o `feature.json` canônico (shape em `.morph/framework/schemas/feature.schema.json`) num passo só, server-side. Não crie a estrutura à mão nem dependa do nascimento implícito via hook no primeiro Write. Depois siga o passo 2.
+  - Caso contrário: rode `morph-spec create {feature-name} --description "<resumo do pedido do usuário>"` — cria `.morph/features/{feature-name}/0-proposal/` e o `feature.json` canônico (shape em `.morph/framework/schemas/feature.schema.json`) num passo só, server-side, com `name`+`description` carimbados. A `--description` é **obrigatória** no nascimento (ou `--request`, que a semeia). Não crie a estrutura à mão nem dependa do nascimento implícito via hook no primeiro Write. Depois siga o passo 2.
 
 ### 2. Invocar `Skill(morph-brainstorming)`
 

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.1"
+cliVersion: "8.4.0"
 ---
 
 # 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.2.1"
+cliVersion: "8.4.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.1"
+cliVersion: "8.4.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"