@polymorphism-tech/morph-spec 8.2.0 → 8.3.0

package/docs/QUICKSTART.md

@@ -19,11 +19,11 @@ morph-spec init
 ```
 
 `init` does the following:
-- Auto-detects your stack (Blazor, Next.js, Node.js, monorepo)
+- Auto-detects your stack (.NET, Next.js, Node.js, monorepo)
 - Creates `.morph/` with framework files, standards, and templates
 - Creates `.morph/context/` with inferred project context
 - Installs `.claude/skills/`, `.claude/agents/`, `.claude/rules/`
-- Writes `.claude/settings.local.json` with 10 Claude Code hooks
+- Writes `.claude/settings.local.json` with the fail-open Claude Code hooks (see `docs/ARCHITECTURE.md`)
 - Copies `CLAUDE.md` with runtime instructions
 
 Verify the installation:
@@ -44,42 +44,31 @@ Open your project in Claude Code and run:
 
 Replace `my-feature` with a short kebab-case name for your feature (e.g., `user-notifications`, `payment-flow`).
 
-The proposal pipeline runs phases 0–6 with three approval gates:
+The proposal pipeline runs the `proposal` and `plan` phases (plus the optional `uiux` phase), with an approval gate at each:
 
-### Phase 0 — Proposal
+### Proposal (Gate 1)
 
-Claude analyzes your request, detects which agents are relevant, and produces `0-proposal/proposal.md`. You review it and approve (or request changes).
+Claude analyzes your request, detects the relevant stack and standards, and produces `0-proposal/proposal.md`. You review it and approve (or request changes).
 
-### Phase 1 — Setup
+### UI/UX — optional (Gate)
 
-Loads project context from `.morph/context/`, confirms stack and active agents. No approval needed.
+Only runs for UI-heavy features. Claude generates, under `1-design/`:
+- `design-system.md` — colors, typography, spacing
+- `mockups.md` — ASCII wireframes
+- `components.md` — component specs
+- `flows.md` — user flows and edge cases
 
-### Phase 2 — UI/UX (conditional)
+You approve the UI design before moving on.
 
-Only runs if frontend agents are active. Claude generates:
-- `1-design/design-system.md` — colors, typography, spacing
-- `1-design/mockups.md` — ASCII wireframes
-- `1-design/components.md` — component specs
-- `1-design/flows.md` — user flows and edge cases
+### Plan (Gate 2)
 
-You approve the UI design before design phase begins.
+Claude produces, under `2-plan/`:
+- `spec.md` — full requirements, use cases, validations
+- `mandate.md` — the implementation contract (stack defaults, forbidden patterns)
+- `tasks.json` — ordered task breakdown (`T001`, `T002`, …)
+- `decisions.md` — architectural decision records (optional)
 
-### Phase 3 — Design
-
-Claude produces the technical specification:
-- `2-design/spec.md` — full requirements, use cases, validations
-- `2-design/contracts.cs` — C# interfaces, DTOs, enums
-- `2-design/decisions.md` — architectural decision records (ADRs)
-
-You review and approve the design.
-
-### Phase 4 — Clarify
-
-Claude identifies 3–7 ambiguities in the spec, asks you to resolve them, then updates the spec. No gate.
-
-### Phase 6 — Tasks
-
-Claude breaks the spec into atomic tasks (`T001`, `T002`, …) saved to `3-tasks/tasks.md`. You approve the task list.
+Claude identifies ambiguities in the spec and resolves them with you before finalizing. You review and approve the spec + mandate + task list together.
 
 At this point, planning is complete:
 
@@ -95,11 +84,11 @@ At this point, planning is complete:
 /morph-apply my-feature
 ```
 
-Claude reads `spec.md`, `contracts.cs`, and `tasks.md`, then implements task by task:
-- Starts each task, writes the code, marks it done
-- Runs 5 validators automatically after each task: security, architecture, packages, design system, Blazor concurrency
-- Auto-checkpoints every 3 tasks (validates, saves state)
-- Generates `4-implement/recap.md` on completion
+Claude reads `spec.md`, `mandate.md`, and `tasks.json`, then implements task by task with auto-advance (no pause between tasks unless there's a blocking ambiguity):
+- Tracks task progress with the native `TaskCreate`/`TaskUpdate` tools, persisted to `tasks.json`
+- Runs the validators relevant to your stack after each task (e.g. `architecture`/`packages`/`contract-compliance` for .NET, `nextjs-component`/`css`/`design-system` for Next.js) via `morph-spec verify`
+- Applies `morph-eval` after each task — a score below 9 triggers an autonomous correction loop, not a pause
+- Generates `3-implement/recap.md` on completion, then Gate 3 review (`4-review/`)
 
 ---
 
@@ -108,21 +97,16 @@ Claude reads `spec.md`, `contracts.cs`, and `tasks.md`, then implements task by
 Check feature state:
 
 ```bash
-morph-spec state get my-feature
 morph-spec status my-feature
 ```
 
-Advance to the next phase manually (when needed):
+Approve the current gate and scaffold the next phase folder in one step:
 
 ```bash
-morph-spec phase advance my-feature
+morph-spec advance my-feature
 ```
 
-Mark a task complete:
-
-```bash
-morph-spec task done my-feature T001
-```
+Task progress is tracked with the native `TaskCreate`/`TaskUpdate` tools and persisted to `tasks.json` — there is no separate CLI command for marking a task done.
 
 Run validators at any time:
 
@@ -195,23 +179,23 @@ morph-spec worktree list
 
 ## Multiple features
 
-You can have multiple features in progress simultaneously. Each has its own directory under `.morph/features/`:
+You can have multiple features in progress simultaneously. Each has its own directory under `.morph/features/`, with its own committed `feature.json`:
 
 ```
 .morph/features/
 ├── user-notifications/
+│   ├── feature.json
 │   ├── 0-proposal/
-│   ├── 2-design/
-│   └── 3-tasks/
+│   └── 2-plan/
 └── payment-flow/
-    ├── 0-proposal/
-    └── 2-design/
+    ├── feature.json
+    └── 0-proposal/
 ```
 
-See all feature states:
+See every active feature — root and worktrees — with phase, gates, and activity:
 
 ```bash
-morph-spec state list
+morph-spec fleet
 ```
 
 ---
@@ -256,4 +240,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.2.0 by Polymorphism Tech*
+*morph-spec v8.3.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -26,7 +26,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - Apresentar gates com o template fixo definido em MORPH.md / morph-plan.
 - Registrar decisões não triviais em `decisions.md`.
 - Aplicar `morph-eval` após cada tarefa; silêncio em score ≥ 9 é o sinal correto. Score < 9 dispara o loop de correção autônomo (re-implementa, sem pausa), não escala ao humano entre tarefas. No Gate 3, o score composto da feature vem do **avaliador independente** despachado pela `morph-review` (persona `evaluator`, contexto fresco) — nunca de auto-avaliação de quem implementou.
-- Incluir as 3 cláusulas do contrato do relatório final em todo dispatch de sub-agent (**ato final = o relatório é a ÚLTIMA MENSAGEM DE TEXTO do sub-agent, com os 4 itens obrigatórios (o quê / arquivos / problemas / auto-score 0-10) — ela é o valor de retorno e chega inteira ao orquestrador; não chamar `SendMessage`, que gera um evento a mais e custa um turno inútil**; não tocar tasks.json/feature.json/board; sem build/test da suíte compartilhada em batch paralelo) — templates em `morph-implement` §4 e `morph-apply` §3b.
+- Incluir as 3 cláusulas do contrato do relatório final em todo dispatch de sub-agent (**o sub-agent GRAVA o relatório em arquivo canônico ANTES de encerrar — `.morph/features/{f}/3-implement/reports/{taskId}.md`, ou `4-review/evaluator-report.md` para o avaliador — com os 4 itens obrigatórios (o quê / arquivos / problemas / auto-score 0-10); esse arquivo é o valor de retorno autoritativo, a última mensagem de texto é cortesia best-effort e pode não chegar inteira; ainda assim não chamar `SendMessage`, que gera um evento a mais e custa um turno inútil**; não tocar tasks.json/feature.json/board; sem build/test da suíte compartilhada em batch paralelo) — templates em `morph-implement` §4 e `morph-apply` §3b. **O orquestrador lê o arquivo ao retomar controle** — nunca confia só na mensagem de retorno da tool.
 
 ## Slash commands
 
@@ -45,7 +45,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `morph-spec advance <feature>` — aprova o gate da fase corrente **e** cria a pasta da próxima fase num passo só (`--design` toma o ramo opcional de uiux a partir da proposta).
 - `morph-spec archive <feature>` — arquiva a feature (atômico, git-aware); é o que `/morph-archive` chama.
 - `morph-spec dag <feature>` — análise do DAG de tasks.json com decisão sequencial vs paralelo **ponderada por effort** (raízes S vão inline, nunca ganham agente próprio).
-- `morph-spec score <feature> <task> <score> [--dims a,c,q,t]` — grava `taskScores` no feature.json com timestamp server-side; **nunca edite taskScores à mão**.
+- `morph-spec score <feature> <task> <score> [--dims a,c,q,t]` — grava `taskScores` no feature.json com timestamp server-side; **nunca edite taskScores à mão**. Em PowerShell, cite o valor de `--dims` entre aspas (`--dims "9.5,9,9,9"`) — sem aspas, a lista pode chegar como tokens separados; o parser aceita ambas as formas, mas citar evita qualquer ambiguidade.
 - `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]` — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
 - `morph-spec create <feature> --type <feature|bug|chore|hotfix> [--request "<txt>"] [--worktree]` — cria a estrutura da feature + `feature.json` canônico explicitamente (nascimento explícito no início da proposal; o hook state-sync continua cobrindo o caminho implícito como fallback). `--type` classifica direto; `--request "<pedido>"` roda o detector determinístico (empate/sem sinal sai com exit 2 e candidatos — a LLM decide e re-roda com `--type`); `--worktree` já nasce a feature no seu worktree próprio.
 - `morph-spec retype <feature> <newType>` — muda o tipo de trabalho mid-flight; desfaz só os gates carimbados por política, preserva aprovações humanas; bloqueado após o Gate 3.
@@ -53,6 +53,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `morph-spec worktree setup|link|finish|list` — gerencia o ciclo do worktree por feature (`setup` cria `.worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `finish` faz merge `--no-ff`, limpa e libera o bloco; `list` mostra fase/gate de cada worktree ativo).
 - `morph-spec handoff <feature>` — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`.
 - `morph-spec fleet` — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, portas, handoff e atividade. Use entre sessões para decidir onde atuar.
+- `morph-spec telemetry [--json] [--feature <f>] [--limit <n>]` — reconstrói o caminho de execução da sessão a partir de `.morph/logs/events.jsonl` (skills invocadas, personas despachadas + prompts, standards/base de conhecimento lidos, mix de tools, prompts do usuário). Capturado silenciosamente pelo hook `telemetry-log` em todo tool call e todo UserPromptSubmit.
 
 ## Skills core (em `.claude/skills/`)
 

package/framework/MORPH.md

@@ -269,14 +269,32 @@ Inline (sem dispatch) é aceitável para tasks curtas (effort S/M) **dentro do d
 - Contexto de outras tarefas não relacionadas
 - Outputs de ferramentas não pertinentes à tarefa
 
-**O que receber de volta:**
+**O ARQUIVO é o retorno, a última mensagem é cortesia.** Em uso real (feature `config-tenant-split`,
+MORPH_GHLBrain, 2026-07-22 — overnight com dispatch de sub-agents), o evento recebido de volta do
+sub-agent foi só um `idle_notification`, sem o texto — o orquestrador teve que reconstruir o
+relatório do disco e pedir via `SendMessage` que o avaliador o persistisse. A última mensagem de
+texto **pode não chegar** inteira ao orquestrador; por isso ela deixou de ser o canal
+autoritativo. O sub-agent **sempre** grava o relatório também em um arquivo canônico:
+
+- Task de implementação: `.morph/features/{feature}/3-implement/reports/{taskId}.md` (um arquivo
+  por task concluída, mesmo quando uma única sessão de sub-agent cobre várias tasks de um fluxo).
+- Avaliador do Gate 3 (`morph-evaluator`): `.morph/features/{feature}/4-review/evaluator-report.md`
+  — o relatório BRUTO do avaliador; a `morph-review` o lê e sintetiza o `review-report.md`
+  apresentado no Gate 3 (os dois nunca colidem: um é saída crua do sub-agent, o outro é a curadoria
+  do orquestrador).
+
+O orquestrador **lê o arquivo** ao retomar controle após o dispatch — nunca confia apenas na
+mensagem de retorno da tool. Se a mensagem de texto final chegou inteira, ótimo (economiza uma
+leitura); se não chegou, o arquivo já está lá.
+
+**O que receber de volta (no arquivo, e na mensagem final quando ela chega):**
 - O que foi feito (2-3 frases)
 - Arquivos modificados (lista)
 - Problemas encontrados e como foram resolvidos
 - Auto-score 0-10 com justificativa em uma linha
 
 **Contrato do relatório final** (cláusulas que todo prompt de dispatch inclui — ver templates em `morph-implement` §4 e `morph-apply` §3b):
-1. **ATO FINAL: o seu relatório é a sua ÚLTIMA MENSAGEM DE TEXTO** — ela é o valor de retorno do sub-agent e chega inteira ao orquestrador. **Não chame `SendMessage`**: ele gera um evento a mais (o teammate-message) além da notificação de término, custando um turno inútil ao orquestrador. Conteúdo obrigatório: (1) o que foi feito em 2-3 frases, (2) arquivos modificados, (3) problemas encontrados e como foram resolvidos, (4) auto-score 0-10 com justificativa em uma linha. Relatório oco ou sem os 4 itens é **falha de protocolo** — registrada no recap.
+1. **GRAVE o relatório no arquivo canônico do seu dispatch ANTES de encerrar** — é o valor de retorno autoritativo desta sessão, não a sua última mensagem de texto (que é cortesia best-effort e pode não chegar inteira ao orquestrador). Conteúdo obrigatório, idêntico no arquivo: (1) o que foi feito em 2-3 frases, (2) arquivos modificados, (3) problemas encontrados e como foram resolvidos, (4) auto-score 0-10 com justificativa em uma linha. Relatório ausente, oco, ou sem os 4 itens é **falha de protocolo** — registrada no recap. Ainda assim **não chame `SendMessage`**: ele gera um evento a mais (o teammate-message) além da notificação de término, custando um turno inútil ao orquestrador — a mensagem de texto final (cortesia) já é entregue automaticamente.
 2. Não tocar em `tasks.json`, `feature.json`, `state.json` nem no board de sessão (TaskCreate/TaskUpdate) — todo estado é gravado exclusivamente pelo orquestrador.
 3. **Verificação em batch paralelo — condicional ao isolamento:** em batch **sem isolamento** (agentes na mesma working tree), não rode build/test da suíte compartilhada — a verificação (`morph-spec verify`) é do orquestrador, uma vez, pós-batch. Em batch **com `isolation: "worktree"`** (quando o `morph-spec dag` recomenda, por colisão de `outputs` entre fluxos), a regra se inverte: rode build/test **dentro do seu worktree**, commite o trabalho na branch do worktree como último ato antes do relatório, reporte a branch + status de build, e **nunca** faça merge nem toque na árvore principal — a integração é do orquestrador.
 

package/framework/agents.json

@@ -64,6 +64,7 @@
         "ai-agents-prompts-in-db",
         "ai-agents-rag-custom-pgvector",
         "ai-agents-middleware-patterns",
+        "ai-agents-observability-patterns",
         "ai-agents-multi-agent-patterns"
       ],
       "mcp": ["context7"],
@@ -125,7 +126,8 @@
       "standards": [
         "backend-integrations-hangfire-hangfire-jobs",
         "infrastructure-docker-coolify-deploy",
-        "backend-dotnet-scrutor"
+        "backend-dotnet-scrutor",
+        "ai-agents-observability-patterns"
       ],
       "mcp": ["context7"],
       "model": "sonnet",

package/framework/hooks/README.md

@@ -51,7 +51,9 @@ framework/hooks/
 | **PostToolUse** (Write\|Edit) | trace-autogen.js | State sync | Auto-generates `.morph/traces/YYYY-MM-DD-{feature}-implement.json` from tasks.json + recap.md + taskScores on every tasks.json write — the skills never write traces by hand |
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | state-sync.js | State sync | Autonomous state updates (feature register, output tracking, gate approval) |
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | gate-guard.js | Advisory | Warns (never blocks) when a gate action disagrees with the persisted gateDecisions; logs one `coherent`/`divergent` line per check in `.morph/logs/activity.json` (issue #63) |
+| **PostToolUse** (all tools) | telemetry-log.js | Telemetry | Appends every tool call (skill, sub-agent dispatch + prompt, knowledge-base read, bash/edit) to `.morph/logs/events.jsonl`; silent, fail-open — the NLH execution-path capture read back by `morph-spec telemetry` |
 | **PostToolUse** (all tools) | loop-detect.js | Advisory | Warns when the last 8 actions collapse to ≤2 unique signatures |
+| **UserPromptSubmit** | telemetry-log.js | Telemetry | Appends the user's prompt to the same `events.jsonl` stream; silent, fail-open |
 | **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift; build check; session snapshot |
 
 ## Design Principles
@@ -112,6 +114,7 @@ All Claude Code hooks import from `framework/hooks/shared/`:
 | `phase-utils.js` | Phase constants, path extraction, file classification |
 | `hook-response.js` | `block(reason)`, `approve(context)`, `injectContext(text)`, `pass()` |
 | `stdin-reader.js` | `readStdin()` — Promise-based stdin JSON reader |
+| `telemetry-logger.js` | `appendTelemetryEvent()`, `readTelemetryEvents()` — append-only JSONL event stream (`.morph/logs/events.jsonl`) |
 
 `injectContext(text)` is how `worktree-context.js` (and any other SessionStart hook) delivers context: it emits `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": text } }` on stdout. Claude Code only honors additional context nested under `hookSpecificOutput` — a bare top-level field is ignored.
 

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -52,7 +52,13 @@ function diffPlanContract(oldDoc, newDoc, mutableFields) {
   const violations = [];
   const mutable = new Set(mutableFields);
 
-  if (oldDoc.version !== newDoc.version) {
+  // Backfilling a previously-absent `version` (undefined → any value) is a
+  // benign schema-tooling update, not a plan-contract change — it's what
+  // lets legacy tasks.json adopt the field so `morph-spec dag` can analyze
+  // it without a lenient fallback. An actual change between two SET
+  // versions is still a real contract change and stays blocked.
+  const versionBackfilled = oldDoc.version === undefined && newDoc.version !== undefined;
+  if (!versionBackfilled && oldDoc.version !== newDoc.version) {
     violations.push(`'version' changed (${oldDoc.version} → ${newDoc.version})`);
   }
   if (oldDoc.feature !== newDoc.feature) {

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/build-check.js

@@ -84,7 +84,14 @@ export function getBuildSteps(stack, { cwd, frontendPath, backendPath } = {}) {
 
   if (isFrontendStack(s)) {
     const frontendDir = frontendPath ? join(cwd, frontendPath) : cwd;
-    if (existsSync(join(frontendDir, 'tsconfig.json'))) {
+    // node_modules guard (same fail-open as post-edit-typecheck.js): a fresh worktree before
+    // `morph-spec worktree link` has tsconfig.json (versioned) but no toolchain — running
+    // `npx tsc` there fetches an unrelated "tsc" package and fails noisily. No toolchain →
+    // no tsc step; the real typecheck runs wherever node_modules exists (root/CI).
+    if (
+      existsSync(join(frontendDir, 'tsconfig.json')) &&
+      existsSync(join(frontendDir, 'node_modules'))
+    ) {
       steps.push({ command: TSC_BUILD_CMD, cwd: frontendDir });
     }
   }

package/framework/hooks/shared/payload-utils.js

@@ -93,7 +93,16 @@ export function getToolName(payload) {
  * Build a normalized signature for loop detection.
  * - Edit/Write: "Edit:normalized/file/path"
  * - Bash: "Bash:first two words" (e.g., "Bash:npm test")
- * - Other: just the tool name
+ * - Every other tool WITH input: "Tool:<truncated JSON of tool_input>"
+ * - No tool_input at all: just the tool name
+ *
+ * The general (non-Edit/Write/Bash) case matters: a burst of `Read`/`Skill`/
+ * `Grep`/`Agent` calls against DIFFERENT targets (phase-context loading,
+ * post-task evaluation reads, parallel subagent dispatch) is normal work, not
+ * a loop. Collapsing every one of them to the bare tool name is what made
+ * loop-detect fire on exactly that legitimate traffic — a real, reported
+ * false positive. Folding in the actual input (rather than hand-listing a
+ * target field per tool) fixes it uniformly for every tool at once.
  *
  * @param {Object} payload - Hook payload from stdin
  * @returns {string} Signature string
@@ -116,5 +125,10 @@ export function getCommandSignature(payload) {
     return words ? `Bash:${words}` : 'Bash';
   }
 
-  return tool;
+  try {
+    const json = JSON.stringify(input).replace(/\\/g, '/');
+    return json ? `${tool}:${json.slice(0, 200)}` : tool;
+  } catch {
+    return tool;
+  }
 }

package/framework/hooks/shared/phase-utils.js

@@ -35,6 +35,7 @@ export const OUTPUT_PHASE_MAP = {
   decisions: 'plan',
   recap: 'implement',
   reviewReport: 'review',
+  evaluatorReport: 'review',
 };
 
 /** Map filename → output type (camelCase) */
@@ -52,6 +53,7 @@ export const FILENAME_TO_OUTPUT = {
   'decisions.md': 'decisions',
   'recap.md': 'recap',
   'review-report.md': 'reviewReport',
+  'evaluator-report.md': 'evaluatorReport',
 };
 
 /** Protected spec files and the approval gate that locks them */

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

@@ -195,12 +195,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.0"
+cliVersion: "8.3.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.0"
+cliVersion: "8.3.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.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-apply
@@ -135,11 +135,16 @@ dispatch Agent (subagent_type: "morph-{id}") with prompt:
     Não modifique spec.md, mandate.md.
 
     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 itens abaixo, é falha de protocolo.
+    1. GRAVE um relatório por task concluída em
+       `.morph/features/{feature}/3-implement/reports/{taskId}.md` ANTES de
+       encerrar — mesmo quando esta sessão cobre várias tasks do fluxo, um
+       arquivo por task. Esse arquivo é o valor de retorno autoritativo; a sua
+       última mensagem de texto é cortesia best-effort e 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 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 (status de task, scores, gates) é
        gravado exclusivamente pelo orquestrador.
@@ -163,7 +168,7 @@ dispatch Agent (subagent_type: "morph-{id}") with prompt:
 
 > **Alternativa quando os fluxos tocam os mesmos projetos/arquivos** (ex.: o mesmo csproj de testes compartilhado): siga a §3b-w abaixo em vez desta seção — despache com `isolation: "worktree"`, cada agente trabalha numa working tree própria e o orquestrador integra ao final.
 
-Aguardar todos os agentes terminarem — o relatório de cada um chega como o resultado do seu dispatch. Se um relatório vier oco ou sem os itens da cláusula 1, registre a falha de protocolo no recap. Depois, sequencialmente:
+Aguardar todos os agentes terminarem, depois **ler primeiro** `.morph/features/{feature}/3-implement/reports/{taskId}.md` de cada task — é o valor de retorno autoritativo; a mensagem de texto do dispatch, se chegou inteira, é só um atalho que economiza essa leitura. Se um arquivo vier ausente, oco, ou sem os itens da cláusula 1, registre a falha de protocolo no recap. Depois, sequencialmente:
 - **Rodar `morph-spec verify {feature} --json` uma única vez, pós-batch** (escopo feature) — os agentes não a rodaram (cláusula 3). Vermelho: use `verify.feedback` para corrigir/redespachar ANTES de qualquer morph-eval. (Com isolamento por worktree, cada agente já rodou o verify dentro do seu worktree; o orquestrador roda o verify compartilhado UMA vez após o merge — ver §3b-w.)
 - Para cada relatório retornado:
   - Aplicar `Skill(morph-eval)`.

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.0"
+cliVersion: "8.3.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.0"
+cliVersion: "8.3.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.0"
+cliVersion: "8.3.0"
 ---
 
 # morph-hotfix