@polymorphism-tech/morph-spec 7.8.1 → 7.9.1

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 7.8.1  
+**Version:** 7.9.1  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -365,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v7.8.1 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v7.9.1 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -14,7 +14,7 @@ import chalk from 'chalk';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { readFileSync } from 'fs';
-import { renderLogo } from '../src/utils/banner.js';
+import { renderLogo, maybePrintFirstRunBanner } from '../src/utils/banner.js';
 
 // === Project / install ===
 import { initCommand } from '../src/commands/project/init.js';
@@ -30,6 +30,8 @@ import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/
 import { advanceCommand } from '../src/commands/state/advance.js';
 import { archiveCommand } from '../src/commands/state/archive.js';
 import { scoreCommand } from '../src/commands/state/score.js';
+import { gateDecisionCommand } from '../src/commands/state/gate-decision.js';
+import { createCommand } from '../src/commands/state/create.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -57,6 +59,16 @@ const banner = `${renderLogo(pkg.version)}
   ${chalk.dim('Spec-driven development harness for Claude Code — by Polymorphism Tech')}
 `;
 
+// First run after an install/upgrade: show the install banner (npm ≥7 hides
+// postinstall output). Skipped for --version/--help (parsed/already-bannered)
+// and for non-TTY output — see maybePrintFirstRunBanner.
+const argvRest = process.argv.slice(2);
+const skipFirstRun = argvRest.length === 0 ||
+  argvRest.some(a => ['-V', '--version', '-h', '--help'].includes(a));
+if (!skipFirstRun) {
+  maybePrintFirstRunBanner({ version: pkg.version, nodeVersion: process.version });
+}
+
 program
   .name('morph-spec')
   .description('MORPH-SPEC Framework CLI')
@@ -146,6 +158,23 @@ program
   .option('--reason <reason>', 'Reason for revocation')
   .action((feature, gate, options) => unapproveCommand(feature, gate, options));
 
+program
+  .command('gate-decision <feature> <gate>')
+  .description('Record the trust decision for a gate in feature.json (gateDecisions, server-side timestamp)')
+  .option('--pause <bool>', 'Whether the gate must pause for a human (true|false) — required')
+  .option('--reason <text>', 'Why this decision was taken (defaults by pause value)')
+  .option('--signals <json>', 'Risk signals as a JSON object, e.g. \'{"taskCount":12,"evalScore":9.2}\'')
+  .option('--trust <mode>', 'Trust mode used for the decision (default: config.json → trust, or "auto")')
+  .option('--json', 'Output as JSON')
+  .action((feature, gateArg, options) => gateDecisionCommand(feature, gateArg, options));
+
+program
+  .command('create <feature>')
+  .description('Create the feature folder structure + canonical feature.json (explicit birth — see framework/schemas/feature.schema.json)')
+  .option('--status <status>', 'Initial feature status (default: in_progress)')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => createCommand(feature, options));
+
 program
   .command('score <feature> <task> <score>')
   .description('Record a task eval score in feature.json (taskScores, server-side timestamp)')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "7.8.1",
+  "version": "7.9.1",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -12,6 +12,10 @@ morph-spec doctor                               # health check
 morph-spec --version
 ```
 
+> `npm i -g ...@latest` deu `ETARGET` logo após uma release? O CDN do npm
+> leva alguns minutos para propagar o `latest` — instale com a versão
+> explícita (`npm i -g @polymorphism-tech/morph-spec@X.Y.Z`) ou aguarde.
+
 ---
 
 ## Phase workflow
@@ -196,4 +200,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v7.8.1 by Polymorphism Tech*
+*morph-spec v7.9.1 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v7.8.1 by Polymorphism Tech*
+*morph-spec v7.9.1 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -25,7 +25,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 de protocolo em todo dispatch de sub-agent (relatório final obrigatório; 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 de protocolo em todo dispatch de sub-agent (**ato final = relatório via `SendMessage` para `main`** — última mensagem em texto não chega ao orquestrador; não tocar tasks.json/feature.json/board; sem build/test da suíte compartilhada em batch paralelo) — templates com exemplo literal em `morph-implement` §4 e `morph-apply` §3b. O hook `subagent-report-guard` bloqueia uma vez o encerramento de subagent despachado sem SendMessage.
 
 ## Slash commands
 
@@ -44,6 +44,8 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `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 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>` — 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).
 
 ## Skills core (em `.claude/skills/`)
 

package/framework/MORPH.md

@@ -123,9 +123,10 @@ Não invente caminhos alternativos.
 
 ### Traces (`.morph/traces/`)
 
-Cada sessão de trabalho produz um trace JSON em `.morph/traces/YYYY-MM-DD-{feature}-{phase}.json`.
+Cada fase de implementação produz um trace JSON em `.morph/traces/YYYY-MM-DD-{feature}-{phase}.json`.
 O trace registra tarefas, scores de eval, standards consultados e sub-agents despachados.
 O formato canônico está em `.morph/framework/evals/trace-schema.md` (criado na issue #17).
+**O trace é gerado automaticamente pelo hook `trace-autogen`** a cada write de `tasks.json`, a partir de tasks.json + recap.md + `taskScores` do feature.json — as skills não o escrevem à mão (a escrita manual foi removida da cerimônia por task).
 Traces são ignorados pelo git (`.gitignore`) e servem para análise do harness — não fazem parte da entrega da feature.
 
 ---
@@ -196,7 +197,7 @@ Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `
 
 Isso mantém o audit trail honesto justamente nos contextos headless (CI, `claude -p`) onde ele mais importa.
 
-**O hook gate-guard.js** confere, sem bloquear, se a ação tomada num gate (pausar via `AskUserQuestion` vs auto-aprovar) bateu com a decisão de trust que a skill computou via `shouldPauseGate`. Para isso, a skill **persiste** a decisão no `feature.json` autoritativo da feature antes de agir: `gateDecisions[gate] = { pause, reason, signals, trust, decidedAt }` (escrito com a tool `Edit` — a allowlist permite `Edit(.morph/features/**)`). Se a ação observada divergir do registro (pausou um gate auto-aprovável, ou auto-aprovou um gate que exigia pausa), o guard injeta um aviso no contexto — a LLM corrige. É um guardrail que nunca bloqueia: a cada conferência ele registra uma linha no activity log (`.morph/logs/activity.json`) com o resultado — `coherent` ou `divergent` — e só injeta aviso quando diverge; sem registro ou erro → silêncio.
+**O hook gate-guard.js** confere, sem bloquear, se a ação tomada num gate (pausar via `AskUserQuestion` vs auto-aprovar) bateu com a decisão de trust que a skill computou via `shouldPauseGate`. Para isso, a skill **persiste** a decisão no `feature.json` autoritativo da feature antes de agir — via `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`, que grava `gateDecisions[gate] = { pause, reason, signals, trust, decidedAt }` com timestamp server-side (shape canônico em `framework/schemas/feature.schema.json`). **Nunca edite `gateDecisions` à mão:** o Edit manual de feature.json colide com o hook state-sync, que reescreve o arquivo entre o Read e o Edit ("file modified since read"). Se a ação observada divergir do registro (pausou um gate auto-aprovável, ou auto-aprovou um gate que exigia pausa), o guard injeta um aviso no contexto — a LLM corrige. É um guardrail que nunca bloqueia: a cada conferência ele registra uma linha no activity log (`.morph/logs/activity.json`) com o resultado — `coherent` ou `divergent` — e só injeta aviso quando diverge; sem registro ou erro → silêncio.
 
 ---
 
@@ -235,7 +236,7 @@ Inline (sem dispatch) é aceitável para tasks curtas (effort S/M) **dentro do d
 - Auto-score 0-10 com justificativa em uma linha
 
 **Protocolo obrigatório do sub-agent** (cláusulas que todo prompt de dispatch inclui — ver templates em `morph-implement` §4 e `morph-apply` §3b):
-1. Ao concluir, entregar o relatório final (última mensagem, ou SendMessage para main se a sessão permanecer viva) — terminar idle sem reportar é **falha de protocolo**; o orquestrador cobra via SendMessage e registra a falha no recap.
+1. **ATO FINAL: enviar o relatório completo via `SendMessage` para `main` antes de encerrar** — a última mensagem em texto NÃO chega ao orquestrador; só SendMessage chega. Terminar idle sem SendMessage é **falha de protocolo**: o hook `subagent-report-guard` bloqueia o encerramento uma vez com a instrução, e a cobrança do orquestrador via SendMessage é apenas o fallback (registrada como falha no recap). Os templates trazem o exemplo literal da chamada.
 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. Em batch paralelo, não rodar build/test da suíte compartilhada — a verificação é do orquestrador, uma vez, pós-batch (alternativa: dispatch com `isolation: "worktree"`, e aí o build roda dentro do worktree).
 

package/framework/evals/trace-schema.md

@@ -45,22 +45,32 @@ Um arquivo por fase. Se a fase for executada em múltiplas sessões, o mesmo arq
 }
 ```
 
-## Quando escrever
+## Como o trace é gerado (automático — não escreva à mão)
 
-| Evento | O que logar |
-|--------|-------------|
-| Task completada | Adicionar entrada em `tasks[]` com todos os campos preenchidos |
-| Eval executada (`morph-eval`) | Preencher `eval_score` e `eval_dimensions` da task correspondente |
-| Fase concluída | Preencher `completed_at` e `phase_summary` |
+O trace é **gerado pelo hook `trace-autogen`** (PostToolUse em Write|Edit) a cada
+write de `2-plan/tasks.json` — o último write da cerimônia de cada task. As skills
+(`morph-implement`, `morph-eval`, `morph-review`) **não escrevem o trace**.
 
-## Regras de escrita
+| Fonte | O que alimenta |
+|-------|----------------|
+| `tasks.json` | conjunto de tasks, `status` (done→completed, skipped→skipped, blocked→failed; pending/in_progress ficam fora), `outputs` → `files_modified` |
+| `recap.md` | `**Standard:**` → `standards_consulted`; `**Persona:**` → `agent_persona` + `sub_agent_dispatched` (`morph-{id}`/`general-purpose` = true) |
+| `feature.json → taskScores` (gravado por `morph-spec score`) | `eval_score` (lastScore) e `eval_dimensions` (camelCase → snake_case) |
 
-- O modelo escreve o trace como arquivo JSON ao final de cada task e ao final da fase.
-- Se um campo não tiver valor disponível, usar `null` — nunca omitir o campo.
-- Manter a estrutura completa para compatibilidade com análise de meta-harness.
-- `session_id` usa o formato `YYYY-MM-DD-HH-MM-SS` do início da sessão atual.
+`completed_at` e `phase_summary` são preenchidos quando nenhuma task resta
+`pending`/`in_progress`. O arquivo existente da mesma feature+fase é atualizado
+in place (`session_id`/`started_at` preservados entre sessões).
+
+**Se o trace parecer incompleto, corrija a FONTE** (um `morph-spec score`
+faltante, um recap sem o bloco `## T{N}`), nunca o trace.
+
+## Regras de geração
+
+- Se um campo não tiver valor disponível, o hook usa `null` — nunca omite o campo.
+- Estrutura completa mantida para compatibilidade com análise de meta-harness.
+- `session_id` usa o formato `YYYY-MM-DD-HH-MM-SS` da primeira geração.
 - `standards_consulted` contém os `id`s do STANDARDS.json, não os paths.
-- `files_modified` usa paths relativos à raiz do repositório.
+- `files_modified` usa paths relativos à raiz do repositório (vem de `outputs`).
 
 ## Motivação
 

package/framework/hooks/README.md

@@ -47,10 +47,12 @@ framework/hooks/
 | **PreToolUse** (Bash) | pre-bash-denylist.js | Block | Blocks `rm -rf .morph/` and direct state edits |
 | **PostToolUse** (Write\|Edit) | post-edit-typecheck.js | Advisory | Debounced `tsc --noEmit` after TS/TSX edits; silent on success |
 | **PostToolUse** (Write\|Edit) | tasks-json-guard.js | Advisory | Validates the written tasks.json schema (status/effort enums); warns so the LLM fixes it immediately |
+| **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) | loop-detect.js | Advisory | Warns when the last 8 actions collapse to ≤2 unique signatures |
 | **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift; build check; session snapshot |
+| **Stop** / **SubagentStop** | subagent-report-guard.js | Block (once) | Blocks a dispatched sub-agent stopping without SendMessage (clause 1 of the dispatch protocol) and injects the exact instruction; `stop_hook_active` prevents loops; inert in the orchestrator's session |
 
 ## Design Principles
 

package/framework/hooks/claude-code/core/subagent-report-guard.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * subagent-report-guard.js — Stop / SubagentStop hook
+ *
+ * Enforces clause 1 of the morph-spec dispatch protocol: a dispatched
+ * sub-agent's FINAL act is SendMessage to the orchestrator (main). Plain text
+ * in the last message never reaches the orchestrator, and an idle agent forces
+ * the costly nag-and-wait cycle (observed 2/2 in real apply sessions —
+ * MORPH_GHLBrain 2026-07-11).
+ *
+ * Detection: the session transcript (JSONL) contains the dispatch-protocol
+ * marker ("Protocolo obrigatório") inside a USER message — that is how the
+ * dispatch prompt arrives in the sub-agent's own transcript. In the
+ * ORCHESTRATOR's transcript the marker only appears inside assistant tool_use
+ * input (the Agent call that did the dispatch), so the orchestrator is never
+ * blocked by this guard. A SendMessage tool_use anywhere in an assistant
+ * message counts as the report.
+ *
+ * Action: block the stop ONCE ({"decision":"block"}) with the exact
+ * instruction to call SendMessage — the agent continues and reports.
+ * stop_hook_active guards against blocking loops. Fail-open on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { stateExists } from '../../shared/state-reader.js';
+import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+
+const PROTOCOL_MARKER = 'Protocolo obrigatório';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Scan a transcript for the dispatch-protocol marker (user messages only) and
+ * for a SendMessage tool call (assistant messages).
+ *
+ * @param {string} path - JSONL transcript path
+ * @returns {{ dispatched: boolean, reported: boolean }}
+ */
+function scanTranscript(path) {
+  const raw = readFileSync(path, 'utf8');
+  let dispatched = false;
+  let reported = false;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let role = null;
+    try {
+      const entry = JSON.parse(line);
+      role = entry?.message?.role ?? entry?.type ?? null;
+    } catch {
+      continue;
+    }
+    if (!dispatched && role === 'user' && line.includes(PROTOCOL_MARKER)) dispatched = true;
+    if (!reported && role === 'assistant' && line.includes('"name":"SendMessage"')) reported = true;
+  }
+  return { dispatched, reported };
+}
+
+try {
+  if (!stateExists(projectDir())) pass();
+
+  const input = readStdin();
+
+  // Never loop: a previous block already forced one continuation — let this
+  // stop through even if the agent still failed to report.
+  if (input.stop_hook_active) pass();
+
+  const transcriptPath = input.transcript_path;
+  if (!transcriptPath || !existsSync(transcriptPath)) pass();
+
+  const { dispatched, reported } = scanTranscript(transcriptPath);
+  if (!dispatched || reported) pass();
+
+  logHookActivity('subagent-report-guard', input.hook_event_name || 'Stop', 'blocked', projectDir());
+  block(
+    '[morph-spec] PROTOCOLO DE RETORNO — você foi despachado com o protocolo obrigatório ' +
+    'mas ainda não chamou SendMessage. Sua última mensagem em texto NÃO chega ao orquestrador. ' +
+    'Antes de encerrar, chame a tool SendMessage com to:"main" e o relatório completo no content: ' +
+    '(1) o que foi feito em 2-3 frases, (2) arquivos modificados, (3) problemas encontrados e ' +
+    'como foram resolvidos, (4) auto-score 0-10. O SendMessage é o seu ato final.'
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/core/trace-autogen.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * trace-autogen.js — PostToolUse hook (Write|Edit)
+ *
+ * Auto-generates the execution trace
+ * `.morph/traces/YYYY-MM-DD-{feature}-implement.json` from tasks.json +
+ * recap.md + feature.json taskScores whenever tasks.json is written during
+ * the implement phase.
+ *
+ * This removes the manual trace-writing step from the skills (friction item
+ * observed in MORPH_GHLBrain 2026-07-11: 5 writes per task). The tasks.json
+ * status flip — the last write of every task's ceremony — now produces the
+ * trace for free: deterministic, idempotent, always in sync with the real
+ * on-disk state. The skills must NOT write traces by hand anymore.
+ *
+ * Sources:
+ *  - tasks.json      → task set, status (done→completed, skipped→skipped,
+ *                      blocked→failed; pending/in_progress stay out), outputs
+ *  - recap.md        → per-task `**Standard:**` id and `**Persona:**` line
+ *  - feature.json    → taskScores (lastScore → eval_score, dimensions →
+ *                      eval_dimensions, camelCase → snake_case)
+ *
+ * The most recent existing `*-{feature}-implement.json` is updated in place
+ * (session_id/started_at preserved); a new dated file is created otherwise.
+ * `completed_at` + phase_summary are stamped when no task is left
+ * pending/in_progress. Fail-open: any error exits 0 silently.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { getFilePath } from '../../shared/payload-utils.js';
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function extractFeature(filePath) {
+  const normalized = String(filePath).replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/([^/]+)\/2-plan\/tasks\.json$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Parse recap.md task blocks (`## T{N} — ...`) into
+ * { [id]: { standard, persona } }. Best-effort: missing fields stay null.
+ */
+function parseRecap(raw) {
+  const map = {};
+  const blocks = String(raw).split(/^## (?=T\d+)/m).slice(1);
+  for (const block of blocks) {
+    const id = (block.match(/^(T\d+)/) ?? [])[1];
+    if (!id) continue;
+    const standard = (block.match(/\*\*Standard:\*\*\s*([^\s(]+)/) ?? [])[1] ?? null;
+    const persona = (block.match(/\*\*Persona:\*\*\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
+    map[id] = { standard, persona };
+  }
+  return map;
+}
+
+/** session_id in the trace-schema format YYYY-MM-DD-HH-MM-SS. */
+function sessionId(d) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}-${p(d.getMinutes())}-${p(d.getSeconds())}`;
+}
+
+/** tasks.json status → trace-schema status. Unsettled statuses are omitted. */
+const STATUS_MAP = { done: 'completed', skipped: 'skipped', blocked: 'failed' };
+
+async function main() {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) return;
+
+  const payload = await readStdin();
+  if (!payload) return;
+
+  const filePath = getFilePath(payload);
+  const feature = filePath ? extractFeature(filePath) : null;
+  if (!feature) return;
+
+  const featureDir = join(cwd, '.morph', 'features', feature);
+  const tasksPath = join(featureDir, '2-plan', 'tasks.json');
+  if (!existsSync(tasksPath)) return;
+  const tasksDoc = JSON.parse(readFileSync(tasksPath, 'utf8'));
+  const tasks = Array.isArray(tasksDoc.tasks) ? tasksDoc.tasks : [];
+
+  let recap = {};
+  const recapPath = join(featureDir, '3-implement', 'recap.md');
+  if (existsSync(recapPath)) {
+    try { recap = parseRecap(readFileSync(recapPath, 'utf8')); } catch { recap = {}; }
+  }
+
+  let taskScores = {};
+  const featureJsonPath = join(featureDir, 'feature.json');
+  if (existsSync(featureJsonPath)) {
+    try { taskScores = JSON.parse(readFileSync(featureJsonPath, 'utf8')).taskScores ?? {}; } catch { taskScores = {}; }
+  }
+
+  const tracesDir = join(cwd, '.morph', 'traces');
+  mkdirSync(tracesDir, { recursive: true });
+
+  // Multi-session phases update the same file incrementally (trace-schema):
+  // reuse the most recent trace for this feature+phase if one exists.
+  const suffix = `-${feature}-implement.json`;
+  const existing = readdirSync(tracesDir)
+    .filter(f => /^\d{4}-\d{2}-\d{2}-/.test(f) && f.endsWith(suffix))
+    .sort()
+    .pop();
+
+  let previous = null;
+  if (existing) {
+    try { previous = JSON.parse(readFileSync(join(tracesDir, existing), 'utf8')); } catch { previous = null; }
+  }
+
+  const now = new Date();
+  const fileName = existing ?? `${now.toISOString().slice(0, 10)}${suffix}`;
+
+  const entries = tasks
+    .filter(t => STATUS_MAP[t.status])
+    .map(t => {
+      const recapEntry = recap[t.id] ?? {};
+      const score = taskScores[t.id];
+      const dims = score?.dimensions;
+      return {
+        id: t.id,
+        title: t.title ?? null,
+        status: STATUS_MAP[t.status],
+        standards_consulted: recapEntry.standard ? [recapEntry.standard] : [],
+        agent_persona: recapEntry.persona ?? null,
+        sub_agent_dispatched: recapEntry.persona
+          ? /^morph-|general-purpose/.test(recapEntry.persona)
+          : false,
+        eval_score: score?.lastScore ?? null,
+        eval_dimensions: dims ? {
+          architecture: dims.architecture ?? null,
+          contracts: dims.contracts ?? null,
+          code_quality: dims.codeQuality ?? null,
+          test_coverage: dims.testCoverage ?? null,
+        } : null,
+        files_modified: Array.isArray(t.outputs) ? t.outputs.filter(o => typeof o === 'string') : [],
+        duration_seconds: null,
+      };
+    });
+
+  const allSettled = tasks.length > 0 &&
+    tasks.every(t => t.status !== 'pending' && t.status !== 'in_progress');
+  const scores = entries.map(e => e.eval_score).filter(s => typeof s === 'number');
+
+  const standardCounts = {};
+  for (const entry of entries) {
+    for (const std of entry.standards_consulted) {
+      standardCounts[std] = (standardCounts[std] ?? 0) + 1;
+    }
+  }
+  const mostUsed = Object.entries(standardCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([std]) => std);
+
+  const trace = {
+    schema_version: '1.0',
+    session_id: previous?.session_id ?? sessionId(now),
+    feature,
+    phase: 'implement',
+    started_at: previous?.started_at ?? now.toISOString(),
+    completed_at: allSettled ? (previous?.completed_at ?? now.toISOString()) : null,
+    tasks: entries,
+    phase_summary: {
+      tasks_completed: entries.filter(e => e.status === 'completed').length,
+      tasks_failed: entries.filter(e => e.status === 'failed').length,
+      avg_eval_score: scores.length
+        ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 10) / 10
+        : null,
+      standards_most_used: mostUsed,
+      sub_agents_dispatched: entries.filter(e => e.sub_agent_dispatched).length,
+    },
+  };
+
+  writeFileSync(join(tracesDir, fileName), JSON.stringify(trace, null, 2), 'utf8');
+}
+
+main().catch(() => { /* fail-open */ }).finally(() => process.exit(0));

package/framework/hooks/shared/tasks-validator.js

@@ -19,6 +19,11 @@ export const VALID_TASK_EFFORT = ['S', 'M', 'L', 'XL'];
  * @param {object} doc - parsed tasks.json
  * @returns {{ valid: boolean, errors: string[] }}
  */
+/** Human-readable type name for error messages ('array', not 'object'). */
+function typeName(value) {
+  return Array.isArray(value) ? 'array' : typeof value;
+}
+
 export function validateTasksDoc(doc) {
   if (!doc || typeof doc !== 'object' || !Array.isArray(doc.tasks)) {
     return { valid: false, errors: ['tasks.json must be an object with a tasks[] array'] };
@@ -33,6 +38,23 @@ export function validateTasksDoc(doc) {
     if (task?.effort !== undefined && !VALID_TASK_EFFORT.includes(task.effort)) {
       errors.push(`task '${id}': invalid effort '${task.effort}' (valid: ${VALID_TASK_EFFORT.join(', ')})`);
     }
+    // Mutable-field type checks with the exact field/value in the message —
+    // a malformed notes/outputs used to surface as the misleading generic
+    // "notes is empty" downstream (MORPH_GHLBrain 2026-07-11).
+    if (task?.notes !== undefined && typeof task.notes !== 'string') {
+      errors.push(`task '${id}': 'notes' must be a string (got ${typeName(task.notes)})`);
+    }
+    if (task?.outputs !== undefined) {
+      if (!Array.isArray(task.outputs)) {
+        errors.push(`task '${id}': 'outputs' must be an array of path strings (got ${typeName(task.outputs)})`);
+      } else {
+        task.outputs.forEach((entry, i) => {
+          if (typeof entry !== 'string') {
+            errors.push(`task '${id}': outputs[${i}] must be a string path (got ${typeName(entry)})`);
+          }
+        });
+      }
+    }
   }
   return { valid: errors.length === 0, errors };
 }
@@ -47,6 +69,12 @@ export function validateTasksDoc(doc) {
  * @param {object} newDoc - parsed proposed tasks.json
  * @returns {string[]} human-readable violation messages (empty = OK)
  */
+/** Compact outputs rendering for messages, capped so huge arrays stay readable. */
+function fmtOutputs(outputs) {
+  const s = JSON.stringify(outputs ?? []);
+  return s.length > 120 ? s.slice(0, 117) + '...' : s;
+}
+
 export function outputsDivergenceViolations(oldDoc, newDoc) {
   const violations = [];
   const oldById = new Map((oldDoc?.tasks ?? []).map(t => [t.id, t]));
@@ -56,13 +84,28 @@ export function outputsDivergenceViolations(oldDoc, newDoc) {
     if (!old) continue;
     const outputsChanged =
       JSON.stringify(old.outputs ?? []) !== JSON.stringify(task.outputs ?? []);
-    const hasNote = typeof task.notes === 'string' && task.notes.trim().length > 0;
-    if (outputsChanged && !hasNote) {
+    if (!outputsChanged) continue;
+
+    // A filled string note explains the divergence — done.
+    if (typeof task.notes === 'string' && task.notes.trim().length > 0) continue;
+
+    // Root-cause specific messages: a malformed notes value is a DIFFERENT
+    // failure than a missing one — claiming "notes is empty" when the agent
+    // just wrote an array reads as a false positive and burns a retry cycle.
+    if (task.notes !== undefined && typeof task.notes !== 'string') {
       violations.push(
-        `task '${task.id}': outputs diverged from the plan but 'notes' is empty — ` +
-        `record why in 'notes' in the same edit`
+        `task '${task.id}': outputs diverged from the plan and 'notes' is not a string ` +
+        `(got ${typeName(task.notes)}) — write the explanation as a single string in 'notes'`
       );
+      continue;
     }
+
+    violations.push(
+      `task '${task.id}': outputs diverged from the plan ` +
+      `(${fmtOutputs(old.outputs)} → ${fmtOutputs(task.outputs)}) but 'notes' is empty — ` +
+      `record why in 'notes' in the same edit. ` +
+      `Deletions and annotations belong in 'notes', not in 'outputs' (outputs = produced paths only).`
+    );
   }
   return violations;
 }