@polymorphism-tech/morph-spec 7.6.0 → 7.7.0

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.6.0  
+**Version:** 7.7.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -365,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v7.6.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v7.7.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -28,6 +28,10 @@ import { worktreeSetupCommand } from '../src/commands/project/worktree.js';
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
 import { advanceCommand } from '../src/commands/state/advance.js';
 import { archiveCommand } from '../src/commands/state/archive.js';
+import { scoreCommand } from '../src/commands/state/score.js';
+
+// === Tasks ===
+import { dagCommand } from '../src/commands/tasks/dag.js';
 
 // === Validation ===
 import { validateCommand } from './validate.js';
@@ -149,6 +153,20 @@ program
   .option('--reason <reason>', 'Reason for revocation')
   .action((feature, gate, options) => unapproveCommand(feature, gate, options));
 
+program
+  .command('score <feature> <task> <score>')
+  .description('Record a task eval score in feature.json (taskScores, server-side timestamp)')
+  .option('--dims <dims>', 'Four comma-separated dimension scores in order a,c,q,t (architecture,contracts,code-quality,test-coverage)')
+  .option('--json', 'Output as JSON')
+  .action((feature, task, score, options) => scoreCommand(feature, task, score, options));
+
+// ─── Tasks ────────────────────────────────────────────────────────────────
+program
+  .command('dag <feature>')
+  .description('Analyze the tasks.json DAG and print the sequential vs parallel dispatch decision (effort-weighted)')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => dagCommand(feature, options));
+
 // ─── Validation ───────────────────────────────────────────────────────────
 program
   .command('validate [validator]')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "7.6.0",
+  "version": "7.7.0",
   "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

@@ -196,4 +196,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v7.6.0 by Polymorphism Tech*
+*morph-spec v7.7.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v7.6.0 by Polymorphism Tech*
+*morph-spec v7.7.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -24,7 +24,8 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - Atualizar o progresso em `tasks.json` ao concluir cada task gravando apenas os campos mutáveis `status`, `outputs` e `notes` — via `Write` OU `Edit` (o hook `protect-spec-files` faz diff semântico e permite qualquer um dos dois desde que o contrato do plano permaneça congelado).
 - 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.
+- 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.
 
 ## Slash commands
 
@@ -37,10 +38,12 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `/morph-preflight` | Validação pré-deploy (specs, contratos, testes, infra) |
 | `/morph-troubleshoot [erro]` | Diagnóstico de erros .NET/Next.js com root-cause analysis |
 
-**Comandos CLI de gate** (a LLM os usa em vez de editar o estado à mão para aprovar/avançar):
+**Comandos CLI de gate e de estado** (a LLM os usa em vez de editar o estado à mão):
 - `morph-spec approve <feature> <gate> --mode auto` — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`.
 - `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**.
 
 ## Skills core (em `.claude/skills/`)
 
@@ -56,8 +59,13 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 ## Personas (em `.claude/agents/`)
 
-7 personas de domínio dispatchávels via Agent tool:
-`dotnet-senior`, `ef-modeler`, `maf-expert`, `nextjs-expert`, `ui-designer`, `infra-engineer`, `evaluator`.
+Despache tasks de domínio com `subagent_type: "morph-{id}"` — a persona é o **system prompt** do subagent registrado (gerado de `agents.json`, a fonte única). Se o tipo não estiver na sua lista de subagents (stack não instalado neste projeto), use o fallback documentado em `morph-apply` §3b: `general-purpose` + campo `persona` de `agents.json` colado no prompt, **registrando o fallback nas `notes` da task**.
+
+<!-- morph-agents:start -->
+_Lista derivada na instalação (`morph-spec setup-infra`). Se este bloco está vazio, rode `morph-spec setup-infra --reinstall`._
+<!-- morph-agents:end -->
+
+Drift entre `agents.json` e os `.md` gerados é detectado por `morph-spec doctor` — nunca edite `.claude/agents/morph-*.md` à mão.
 
 ## Regra de precedência de skills
 

package/framework/MORPH.md

@@ -18,8 +18,8 @@ Entre gates, você opera com autonomia total. O dev valida. Você executa.
 | Tarefa completada na fase implement                                   | Iniciar a próxima task do tasks.json sem aguardar instrução                   |
 | Ambiguidade de escopo coberta pelo mandate                            | Resolver conservadoramente e registrar em decisions.md                        |
 | Ambiguidade bloqueante (requisito ausente ou contraditório)           | UMA pergunta via AskUserQuestion                                              |
-| Sub-agent com auto-score ≥ 7                                          | Integrar ao recap.md e continuar                                              |
-| Sub-agent com auto-score < 7                                          | Aplicar morph-eval antes de aceitar                                           |
+| Sub-agent retornou relatório (qualquer auto-score)                    | Auto-score é triagem, não aprovação: a task só avança com morph-eval ≥ 9      |
+| Sub-agent com auto-score < 7                                          | Re-despachar com feedback específico (ou corrigir inline) antes do morph-eval |
 | Build/typecheck quebra                                                | Corrigir antes de marcar tarefa como done                                     |
 | Score morph-eval ≥ 9                                                  | Silêncio (aprovação implícita), próxima tarefa                                |
 | Score morph-eval < 9 numa task                                        | Loop de correção autônomo: re-implementar com o feedback priorizado, até 3 tentativas, sem pausa humana |
@@ -68,7 +68,8 @@ Responsabilidades: executar tarefas do tasks.json em ordem, consultar standards
 Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durante a implementação vão para o decisions.md com flag "escopo expandido" — o Orchestrator avalia se o tasks.json precisa ser atualizado.
 
 **Evaluator** — ativo após uma tarefa ou fase ser concluída.
-Responsabilidades: aplicar as rubricas em `framework/evals/rubrics/`, produzir score 0-10, emitir feedback priorizado quando score < 9 (que alimenta o loop de correção autônomo do morph-apply), escalar para revisão humana apenas quando o loop de correção se esgotar (3 tentativas sem atingir 9).
+Responsabilidades: aplicar as rubricas em `.morph/framework/evals/rubrics/`, produzir score 0-10, emitir feedback priorizado quando score < 9 (que alimenta o loop de correção autônomo do morph-apply), escalar para revisão humana apenas quando o loop de correção se esgotar (3 tentativas sem atingir 9).
+No **Gate 3** o Evaluator é obrigatoriamente um sub-agent independente: a `morph-review` despacha o subagent registrado `morph-evaluator` (gerado de `agents.json`, tools read-only) com contexto fresco — mandate + diff da implementação + saída real dos testes — e o score composto da feature vem desse retorno, nunca de auto-avaliação de quem implementou.
 Anti-padrão: o Evaluator não reescreve o código que avaliou. Se o score está abaixo de 6, o relatório vai para o humano — não para uma segunda rodada de tentativa automática.
 
 Os papéis não são exclusivos — numa sessão longa você transita entre Orchestrator e Specialist conforme as tarefas avançam. A transição deve ser explícita: antes de mudar de papel, conclua o que estava fazendo ou registre o estado corrente no recap.md.
@@ -123,7 +124,7 @@ Não invente caminhos alternativos.
 
 Cada sessão de trabalho 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 `framework/evals/trace-schema.md` (criado na issue #17).
+O formato canônico está em `.morph/framework/evals/trace-schema.md` (criado na issue #17).
 Traces são ignorados pelo git (`.gitignore`) e servem para análise do harness — não fazem parte da entrega da feature.
 
 ---
@@ -145,7 +146,7 @@ O índice de standards fica em `framework/standards/STANDARDS.json`. Cada entrad
 
 **Como identificar o standard certo:** filtre por `category` primeiro (ex: "architecture", "contracts", "testing"), depois por `tags` (ex: "dotnet", "nextjs", "blazor"). Se dois standards parecem relevantes e há conflito, adote o mais específico ao stack do projeto — e registre o conflito no decisions.md.
 
-O agente responsável por um domínio está listado em `framework/agents.json`. Consulte o campo `persona` do agente para entender o ponto de vista que você deve adotar ao aplicar os standards daquele domínio. A persona define o nível de rigor esperado: um agente de arquitetura tem critérios mais rígidos do que um agente de suporte mensal.
+O agente responsável por um domínio está listado em `.morph/framework/agents.json` (fonte única — os subagents `morph-{id}` em `.claude/agents/` são gerados dele). Consulte o campo `persona` do agente para entender o ponto de vista que você deve adotar ao aplicar os standards daquele domínio quando trabalhar inline. A persona define o nível de rigor esperado: um agente de arquitetura tem critérios mais rígidos do que um agente de suporte mensal.
 
 **Quando não há standard adequado:** registre no decisions.md que nenhum standard cobre o caso, descreva o critério que você adotou e sinalize para revisão futura. Não invente um standard — padrões não documentados são dívida técnica disfarçada.
 
@@ -161,7 +162,7 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), gates **
 - "cancelar feature"   (Gate 3 usa "rollback" em vez de "cancelar")
 ```
 
-**Sinais de risco que forçam pausa em auto** (detectados via `src/lib/risk-detector.js`):
+**Sinais de risco que forçam pausa em auto** (as skills aplicam estas regras em linguagem natural — a tabela abaixo é a fonte única):
 
 | Sinal | Threshold | Quando aplica |
 |-------|-----------|---------------|
@@ -186,7 +187,7 @@ Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `
 
 **Comportamento padrão fora de gate:** trabalhe com autonomia total. Gates só existem nestes três pontos. Não pause para confirmação no meio de implementação a menos que encontre uma ambiguidade de escopo que o mandate não cobre — nesse caso, registre a ambiguidade no decisions.md, resolva da forma mais conservadora possível, e sinalize na entrega da task.
 
-**A aprovação de gate é unificada nos comandos da CLI — a LLM nunca edita o estado à mão para aprovar um gate.** Em `trust: "auto"` (sem `AskUserQuestion`), a skill aprova o gate via `morph-spec approve <feature> <gate> --mode auto`; para aprovar o gate da fase corrente **e** já criar a pasta da próxima fase num passo só, use `morph-spec advance <feature>` (adicione `--design` para tomar o ramo opcional de uiux a partir da proposta) — isso substitui o Edit manual de state.json + `mkdir` da pasta de fase. **O hook state-sync.js** cobre o caminho manual: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", ele registra o gate correspondente no `feature.json` autoritativo da feature com `approvedBy: "manual"` (um humano aprovou no loop), na forma canônica. Nos dois caminhos o gate acaba gravado em `.morph/features/{feature}/feature.json` — nunca via Edit à mão de `state.json`.
+**A aprovação de gate é unificada nos comandos da CLI — a LLM nunca edita o estado à mão para aprovar um gate.** Em `trust: "auto"` (sem `AskUserQuestion`), a skill aprova o gate via `morph-spec approve <feature> <gate> --mode auto`; para aprovar o gate da fase corrente **e** já criar a pasta da próxima fase num passo só, use `morph-spec advance <feature>` (adicione `--design` para tomar o ramo opcional de uiux a partir da proposta) — isso substitui o Edit manual de state.json + `mkdir` da pasta de fase. Os scores por task também têm comando dedicado: `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. **O hook state-sync.js** cobre o caminho manual: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", ele registra o gate correspondente no `feature.json` autoritativo da feature com `approvedBy: "manual"` (um humano aprovou no loop), na forma canônica. Nos dois caminhos o gate acaba gravado em `.morph/features/{feature}/feature.json` — nunca via Edit à mão de `state.json`.
 
 **Registre quem aprovou cada gate (`approvedBy`):** o gate é um objeto `{ approved, timestamp, approvedBy }`.
 - `approvedBy: "auto"` — gate avançado por política `trust: auto` sem decisão humana.
@@ -194,7 +195,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 silencioso, nunca um orquestrador: coerente, 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: `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.
 
 ---
 
@@ -213,6 +214,8 @@ A thread principal é o **Orchestrator**. Trabalho de implementação pesado ou
 
 Inline (sem dispatch) é aceitável para tasks curtas (effort S/M) **dentro do domínio que você já tem carregado em contexto**. Se optar por inline numa task que dispara um gatilho acima, **registre a justificativa em uma linha no decisions.md** ("inline porque o contexto X já está carregado e o overhead de dispatch não compensa") — uma escolha de inline silenciosa numa task pesada/multi-domínio é o anti-padrão.
 
+**Mecanismo de dispatch:** os agents de domínio são subagents **registrados** (`.claude/agents/morph-{id}.md`, gerados de `agents.json` — a fonte única — na instalação). Despache com `subagent_type: "morph-{id}"` (ex.: `morph-dotnet-senior`): a persona é o **system prompt** do subagent, com tools, model e MCPs definidos por domínio no próprio `agents.json` (ex.: `context7` para docs vivas nos implementadores; Stitch/Gemini/Playwright no `morph-ui-designer`; o `morph-evaluator` é read-only). **Fallback** quando o tipo não está registrado (stack não instalado neste projeto): `general-purpose` com o campo `persona` de `agents.json` colado no prompt, **registrado nas `notes` da task**. O `**Persona:**` do recap registra sempre o mecanismo real usado — nunca uma auto-declaração.
+
 **O que passar ao sub-agent:**
 - Especificação da tarefa (do tasks.json)
 - Path do standard relevante (apenas um)
@@ -230,6 +233,11 @@ Inline (sem dispatch) é aceitável para tasks curtas (effort S/M) **dentro do d
 - Problemas encontrados e como foram resolvidos
 - 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.
+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).
+
 O sub-agent deve ser autossuficiente com o que você passou. Se precisar de mais contexto para começar, a tarefa não estava bem especificada — refine antes de despachar.
 
 **Quando NÃO despachar sub-agent:**
@@ -237,11 +245,11 @@ O sub-agent deve ser autossuficiente com o que você passou. Se precisar de mais
 - Quando o feedback do sub-agent precisaria ser discutido em tempo real — dispatch é assíncrono.
 - Quando a tarefa envolve mudanças de arquitetura que o Orchestrator precisa validar antes de executar.
 
-**Após receber o retorno do sub-agent:** leia o auto-score. Se for < 7, aplique a skill morph-eval no resultado antes de aceitar. Se for >= 7 e sem itens bloqueantes, integre o resultado ao recap.md e siga para a próxima tarefa.
+**Após receber o retorno do sub-agent:** leia o auto-score — ele é **triagem, não aprovação**. Se for < 7, re-despache com o feedback específico (ou corrija inline) antes de avaliar. Em qualquer caso, a task só avança quando `morph-eval` der score ≥ 9 (a barra única do §0); integre o resultado ao recap.md e siga para a próxima tarefa.
 
 > **Anti-padrão a evitar:** implementar múltiplas tasks de domínios diferentes inline, em sequência, na thread principal — "eu já sei o padrão de cada uma". Isso é exatamente o sinal de que o sistema de delegação foi ignorado. Quando uma feature cruza ≥2 domínios, o caminho default é o Orchestrator despachando especialistas, não o Orchestrator virando faz-tudo.
 
-**Dispatch em paralelo (multi-agent):** quando há fluxos de trabalho **genuinamente independentes** (ex: a cadeia de backend e a cadeia de frontend de uma mesma feature, que só convergem no fim), despache múltiplos sub-agents **ao mesmo tempo** — um por fluxo — em vez de processá-los em série. O orquestrador analisa o DAG de `tasks.json`, identifica os fluxos independentes (por `dependencies` e por `group`), e dispara o batch paralelo. As regras concretas de decisão sequencial vs. paralelo e o cap de agentes simultâneos vivem na skill `morph-apply` (seção "Análise de DAG"). A thread principal coordena; os especialistas executam — inclusive em paralelo.
+**Dispatch em paralelo (multi-agent):** quando há fluxos de trabalho **genuinamente independentes** (ex: a cadeia de backend e a cadeia de frontend de uma mesma feature, que só convergem no fim), despache múltiplos sub-agents **ao mesmo tempo** — um por fluxo — em vez de processá-los em série. O orquestrador roda `morph-spec dag {feature}` — o comando analisa o DAG de `tasks.json` (por `dependencies` e por `group`), **pondera o esforço** (raízes e fluxos só de tasks S não ganham dispatch próprio: vão inline ou agrupados num único agente) e imprime a decisão pronta. As regras concretas e o cap de agentes simultâneos vivem na skill `morph-apply` (seção "Análise de DAG"). A thread principal coordena; os especialistas executam — inclusive em paralelo.
 
 O padrão de dispatch e o template de prompt para sub-agents estão detalhados em `framework/skills/core/morph-implement/SKILL.md`.
 

package/framework/agents.json

@@ -1,8 +1,8 @@
 {
-  "version": "5.0.0",
+  "version": "5.1.0",
   "schema": "domain-personas",
   "total_agents": 7,
-  "description": "Domain personas dispatched per task by the morph-implement skill. The 3 roles (Orchestrator/Specialist/Evaluator) are assumed by Claude itself per MORPH.md — these are domain personas the Specialist consults when working in a specific area.",
+  "description": "Domain personas dispatched per task via subagent_type morph-{id} (.claude/agents/ generated from this file — single source of truth, ADR-001). Optional per-agent fields: `tools` (comma-separated tool scope; default Read, Write, Edit, Bash, Glob, Grep), `model` (default inherit), `mcp` (registry ids from framework/mcp/registry.json, granted as mcp__{id}). The 3 roles (Orchestrator/Specialist/Evaluator) are assumed by Claude itself per MORPH.md.",
   "agents": {
     "dotnet-senior": {
       "title": ".NET Senior Engineer",
@@ -21,6 +21,7 @@
         "backend-dotnet-vsa-handler-patterns",
         "backend-dotnet-fluent-validation-vsa"
       ],
+      "mcp": ["context7"],
       "persona": "Você é um engenheiro .NET sênior. Pensa em VSA com handlers diretos, result pattern, sealed classes, Guid.CreateVersion7(). Acesso a dados híbrido: IRepository<T> + IUnitOfWork para CRUD, DbContext direto no slice para queries específicas; nunca uma camada de Service/Manager. Não usa exceptions como fluxo. Consulta o standard antes de escrever cada slice. Nomeia tudo em PascalCase para tipos, camelCase para parâmetros."
     },
     "ef-modeler": {
@@ -38,6 +39,7 @@
         "infrastructure-neon-setup",
         "infrastructure-neon-pgvector"
       ],
+      "mcp": ["context7"],
       "persona": "Você é um especialista em EF Core sobre Neon (Postgres). Pensa em migrations explícitas, configurações fluentes, navigation properties bem nomeadas, índices intencionais. Sempre Guid.CreateVersion7() para PKs. Sealed entities. Nunca leak de DbContext fora do handler."
     },
     "maf-expert": {
@@ -61,6 +63,7 @@
         "ai-agents-middleware-patterns",
         "ai-agents-multi-agent-patterns"
       ],
+      "mcp": ["context7"],
       "persona": "Você é especialista no Microsoft Agent Framework (MAF 1.0 GA). Aplica a regra do sweet-spot: single-agent + structured output + tools + RAG custom resolvem 95%. Refere alias do Model Registry, nunca model hardcoded. Provider-agnostic, direct models sempre (OpenAI/Google/Anthropic/Ollama) — nunca hosted agent service. Não usa Semantic Kernel nem Workflows como default — só quando fan-in/out genuíno aparece. Telemetria via AgentOpenTelemetryConsts.DefaultSourceName."
     },
     "nextjs-expert": {
@@ -80,6 +83,7 @@
         "frontend-nextjs-naming-conventions",
         "frontend-nextjs-state-management"
       ],
+      "mcp": ["context7"],
       "persona": "Você escreve Next.js App Router idiomático. Server Components por padrão, Client Components apenas quando há interatividade real. Tailwind + Shadcn + Framer Motion. Tipos via Zod. Nada de getServerSideProps. RSC streaming quando faz sentido."
     },
     "ui-designer": {
@@ -97,6 +101,8 @@
         "frontend-design-system-animations",
         "frontend-nextjs-motion-patterns"
       ],
+      "tools": "Read, Write, Edit, Glob, Grep",
+      "mcp": ["context7", "stitch", "gemini-image", "playwright"],
       "persona": "Você desenha sistemas, não telas isoladas. Pensa em tokens (cor, espaço, tipografia), componentes reutilizáveis, estados (default/hover/focus/disabled/loading/error), acessibilidade WCAG AA. Mockups em Tailwind direto, sem Figma intermediário."
     },
     "infra-engineer": {
@@ -114,7 +120,8 @@
         "infrastructure-docker-coolify-deploy",
         "backend-dotnet-scrutor"
       ],
-      "persona": "Você cuida de infra: jobs assíncronos com Hangfire (apenas quando há razão real), deployment, observabilidade. Pensa em retry, idempotência, dead-letter, métricas. Não inventa infra — usa o que o stack já oferece."
+      "mcp": ["context7"],
+      "persona": "Você cuida de infra: jobs assíncronos com Hangfire (apenas quando há razão real), deployment, observabilidade. Pensa em retry, idempotência, dead-letter, métricas. Não inventa infra — usa o que o stack já oferece. Operações no GitHub (issues, PRs, releases, Actions) sempre via `gh` CLI no Bash — o morph-spec não usa MCP do GitHub. Coolify sempre via SSH + curl na API local — não há MCP nem CLI."
     },
     "evaluator": {
       "title": "Code & Architecture Evaluator",
@@ -126,7 +133,8 @@
       ],
       "stack": ["*"],
       "standards": [],
-      "persona": "Você aplica as rubricas em framework/evals/rubrics/. Não reescreve código — produz scores 0-10 por dimensão (architecture, contracts, code-quality, test-coverage), feedback priorizado acionável, e ação clara (aprovado em >=9 / feedback para o loop de correção em <9). Silêncio em scores ≥ 9 é o sinal correto."
+      "tools": "Read, Glob, Grep",
+      "persona": "Você aplica as rubricas em .morph/framework/evals/rubrics/. Você não participou da implementação — avalia apenas o mandate, o diff e a saída real dos testes que o orquestrador fornece, com contexto fresco. Não reescreve código — produz scores 0-10 por dimensão (architecture, contracts, code-quality, test-coverage), feedback priorizado acionável, e ação clara (aprovado em >=9 / feedback para o loop de correção em <9). Silêncio em scores ≥ 9 é o sinal correto."
     }
   }
 }

package/framework/hooks/README.md

@@ -41,18 +41,16 @@ framework/hooks/
 
 | Event | Hook | Type | Purpose |
 |-------|------|------|---------|
-| **SessionStart** | inject-morph-context.js | Inject context | Shows active feature, phase, pending approvals |
-| **UserPromptSubmit** | enrich-prompt.js | Inject context | Warns about wrong-phase work, injects commands |
 | **PreToolUse** (Write\|Edit) | _(native permissions.deny)_ | Block | Blocks edits to state.json and .morph/framework/ |
-| **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval |
+| **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval; for tasks.json validates the mutable-field diff, the status enum, and requires a `notes` when `outputs` diverge from the plan |
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
-| **PreToolUse** (Bash) | _(prompt-type inline guard)_ | Block | Blocks `rm -rf .morph/` and direct state edits via Claude's reasoning |
-| **PostToolUse** (Write\|Edit\|AskUserQuestion) | state-sync.js | State sync | Autonomous state.json 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 (trust-mode enforcement, issue #63) |
-| **PostToolUse** (Bash) | dispatch.js | Dispatch | Triggers checkpoints on task completion |
-| **PostToolUseFailure** | handle-tool-failure.js | Logging | Appends structured JSON to .morph/logs/tool-failures.log |
-| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/pending gates |
-| **PreCompact** | save-morph-context.js | Snapshot | Saves state to .morph/memory/ before compaction |
+| **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\|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 |
 
 ## Design Principles
 

package/framework/hooks/claude-code/core/gate-guard.js

@@ -8,8 +8,8 @@
  * to state.json (`features[feature].gateDecisions[gate]`) and injects a
  * non-blocking warning when they disagree.
  *
- * It is a silent guardrail, NOT an orchestrator (per MORPH.md): it never
- * blocks, never writes state, and fails open on any error or missing data.
+ * It is a guardrail, NOT an orchestrator (per MORPH.md): it never blocks,
+ * never writes state, and fails open on any error or missing data.
  *
  * Two mismatch directions:
  *  - LLM PAUSED (AskUserQuestion on a gate) but the persisted decision said
@@ -17,12 +17,17 @@
  *  - LLM AUTO-APPROVED (gate became approvedBy:"auto") but the persisted
  *    decision said pause:true → skipped a required human pause. Warn.
  *
- * Coherent action, no persisted decision, or any error → silence.
+ * Observability: every time a gate action is actually checked against a
+ * persisted gateDecisions entry, one line lands in the activity log
+ * (.morph/logs/activity.json) with result 'coherent' or 'divergent' — so a
+ * human can confirm the guard verified coherence instead of absolute silence.
+ * No persisted decision, non-gate action, or any error → silence.
  */
 
 import { readFileSync } from 'fs';
 import { loadState, stateExists } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 function readStdin() {
   try {
@@ -64,7 +69,7 @@ function getDecision(state, feature, gate) {
  * The LLM just asked a gate question. If the persisted decision said this
  * gate should auto-pass (pause:false), the human was interrupted needlessly.
  */
-function checkAskUserQuestion(input, state, feature) {
+function checkAskUserQuestion(input, state, feature, cwd) {
   // Questions live in tool_input.questions[]; answers in tool_response.
   const questions = input.tool_input?.questions;
   const askedTexts = [];
@@ -86,6 +91,7 @@ function checkAskUserQuestion(input, state, feature) {
     const decision = getDecision(state, feature, gate);
     if (!decision) continue; // no persisted decision → nothing to verify
     if (decision.pause === false) {
+      logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
       return injectContext(
         `⚠️ [morph-spec] GATE OVER-PAUSE — você apresentou o Gate "${gate}" via AskUserQuestion, ` +
         `mas a decisão registrada em state.json (gateDecisions.${gate}) era pause:false ` +
@@ -95,18 +101,29 @@ function checkAskUserQuestion(input, state, feature) {
         `caso contrário, evite pausar gates auto-aprováveis.`
       );
     }
+    // The decision said pause:true and the LLM did pause — coherent.
+    logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
+    return pass();
   }
   return pass();
 }
 
+/** True for edits to .morph/state.json (legacy) or a per-feature feature.json (v5). */
+function isGateStateFile(filePath) {
+  const fp = String(filePath ?? '').replace(/\\/g, '/');
+  if (fp.endsWith('.morph/state.json')) return true;
+  return fp.includes('.morph/features/') && fp.endsWith('/feature.json');
+}
+
 /**
- * The LLM just edited state.json. If a gate flipped to approvedBy:"auto" but
- * the persisted decision said pause:true, a required human pause was skipped.
+ * The LLM just edited gate state (state.json legacy, or the authoritative
+ * feature.json in v5). If a gate flipped to approvedBy:"auto" but the
+ * persisted decision said pause:true, a required human pause was skipped.
  */
-function checkStateEdit(input, state, feature) {
-  const filePath = String(input.tool_input?.file_path ?? '').replace(/\\/g, '/');
-  if (!filePath.endsWith('.morph/state.json')) return pass();
+function checkStateEdit(input, state, feature, cwd) {
+  if (!isGateStateFile(input.tool_input?.file_path)) return pass();
 
+  let checked = false;
   const gates = state.features?.[feature]?.approvalGates ?? {};
   for (const gate of ['proposal', 'plan', 'review']) {
     const g = gates[gate];
@@ -115,15 +132,18 @@ function checkStateEdit(input, state, feature) {
     const decision = getDecision(state, feature, gate);
     if (!decision) continue;
     if (decision.pause === true) {
+      logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
       return injectContext(
-        `⚠️ [morph-spec] GATE SKIPPED PAUSE — o Gate "${gate}" foi marcado approvedBy:"auto" em state.json, ` +
+        `⚠️ [morph-spec] GATE SKIPPED PAUSE — o Gate "${gate}" foi marcado approvedBy:"auto", ` +
         `mas a decisão registrada (gateDecisions.${gate}) era pause:true ` +
         `(sinal: ${decision.reason || 'risco detectado'}). ` +
         `Um sinal de risco exigia pausa humana via AskUserQuestion — uma auto-aprovação aqui ignora o trust mode. ` +
         `Reabra o gate com AskUserQuestion (label "aprovado, prosseguir") ou corrija o sinal de risco antes de avançar.`
       );
     }
+    checked = true;
   }
+  if (checked) logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
   return pass();
 }
 
@@ -134,11 +154,11 @@ function main() {
   const input = readStdin();
   const toolName = input.tool_name;
 
-  // Short-circuit before loading state: a Write/Edit only matters if it touched
-  // state.json. Skip the disk read for the dozens of unrelated edits per feature.
+  // Short-circuit before loading state: a Write/Edit only matters if it
+  // touched gate state (state.json legacy, or the v5 per-feature
+  // feature.json). Skip the disk read for unrelated edits.
   if (toolName === 'Edit' || toolName === 'Write') {
-    const fp = String(input.tool_input?.file_path ?? '').replace(/\\/g, '/');
-    if (!fp.endsWith('.morph/state.json')) return pass();
+    if (!isGateStateFile(input.tool_input?.file_path)) return pass();
   } else if (toolName !== 'AskUserQuestion') {
     return pass();
   }
@@ -149,8 +169,8 @@ function main() {
     const feature = findActiveFeature(state);
     if (!feature) return pass();
 
-    if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, state, feature);
-    if (toolName === 'Edit' || toolName === 'Write') return checkStateEdit(input, state, feature);
+    if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, state, feature, cwd);
+    if (toolName === 'Edit' || toolName === 'Write') return checkStateEdit(input, state, feature, cwd);
   } catch {
     // fail-open
   }

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

@@ -37,6 +37,7 @@ import {
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, getToolName } from '../../shared/payload-utils.js';
+import { validateTasksDoc, outputsDivergenceViolations } from '../../shared/tasks-validator.js';
 
 /**
  * Compare two tasks.json structures and return the list of plan-contract
@@ -162,6 +163,18 @@ try {
     }
 
     const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
+
+    // Schema check on the proposed doc: even mutable-field writes must keep a
+    // valid status enum (a leaf agent writing status:"completed" was the
+    // production failure this closes). Only NEWLY introduced schema errors
+    // block — a pre-existing violation must not deadlock progress writes.
+    const preExisting = new Set(validateTasksDoc(oldDoc).errors);
+    violations.push(...validateTasksDoc(newDoc).errors.filter(e => !preExisting.has(e)));
+
+    // Planned-vs-real outputs diff: changing `outputs` is allowed, but the
+    // divergence must be explained in `notes` in the same edit.
+    violations.push(...outputsDivergenceViolations(oldDoc, newDoc));
+
     if (violations.length === 0) {
       // Only mutable progress fields changed — a legitimate implement-phase
       // update via Write OR Edit.
@@ -171,12 +184,14 @@ try {
 
     logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
     block(
-      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-      `This ${toolName} changes the frozen plan contract:\n` +
+      `MORPH-SPEC: '${filename}' write rejected — the '${requiredGate}' gate has been approved.\n` +
+      `This ${toolName} violates the plan contract or the tasks schema:\n` +
       violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
-      `During the implement phase only these fields may change: ${mutableFields.join(', ')}.\n` +
-      `To change the plan itself, ask the user to revoke the '${requiredGate}' gate\n` +
-      `in .morph/state.json, then re-present it for approval.`
+      `During the implement phase only these fields may change: ${mutableFields.join(', ')}\n` +
+      `(status must stay in the schema enum, and outputs that diverge from the plan\n` +
+      `require an explanatory 'notes' in the same edit).\n` +
+      `To change the plan itself, ask the user to revoke the '${requiredGate}' gate,\n` +
+      `then re-present it for approval.`
     );
   }
 

package/framework/hooks/claude-code/core/tasks-json-guard.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * tasks-json-guard.js — PostToolUse hook (validate-and-warn, never block)
+ *
+ * Event: PostToolUse | Matcher: Write|Edit
+ *
+ * After any Write/Edit that touches a tasks.json under .morph/features/,
+ * re-reads the file from disk and validates the schema (status enum, effort
+ * enum). Invalid → injects a warning so the LLM fixes the file immediately;
+ * valid → logs one activity line and stays silent.
+ *
+ * The production failure this guards: a leaf sub-agent wrote
+ * status:"completed" (not in the enum — the schema accepts "done") into
+ * tasks.json and nothing flagged it. The blocking pre-write validation for
+ * post-Gate-2 edits lives in protect-spec-files.js (PreToolUse); this
+ * PostToolUse pass also covers pre-gate authoring (morph-plan) and anything
+ * that landed on disk regardless.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
+import { isFeaturePath, getBasename } from '../../shared/phase-utils.js';
+import { VALID_TASK_STATUS, validateTasksDoc } from '../../shared/tasks-validator.js';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+try {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) pass();
+
+  const payload = readStdin();
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+  if (!isFeaturePath(filePath)) pass();
+  if (getBasename(filePath) !== 'tasks.json') pass();
+
+  const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
+
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(absPath, 'utf-8'));
+  } catch {
+    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+    injectContext(
+      '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
+      'Corrija o arquivo antes de continuar.'
+    );
+  }
+
+  const { valid, errors } = validateTasksDoc(doc);
+  if (!valid) {
+    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+    injectContext(
+      '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
+      errors.map(e => `  • ${e}`).join('\n') +
+      `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`
+    );
+  }
+
+  logHookActivity('tasks-json-guard', 'PostToolUse', 'ok', cwd);
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}