@polymorphism-tech/morph-spec 8.1.2 → 8.2.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:** 8.1.2  
+**Version:** 8.2.1  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -394,4 +394,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.1.2 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.2.1 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -24,6 +24,7 @@ import { updateCommand } from '../src/commands/project/update.js';
 import { doctorCommand } from '../src/commands/project/doctor.js';
 import { statusCommand } from '../src/commands/project/status.js';
 import { worktreeSetupCommand, worktreeLinkCommand, worktreeFinishCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
+import { fleetCommand } from '../src/commands/project/fleet.js';
 
 // === Approval gates (human-only) ===
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
@@ -33,6 +34,7 @@ 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';
 import { retypeCommand } from '../src/commands/state/retype.js';
+import { handoffCommand } from '../src/commands/state/handoff.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -184,7 +186,7 @@ program
 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('--dims <dims...>', 'Four dimension scores in order a,c,q,t (architecture,contracts,code-quality,test-coverage) — comma- or space-separated; quote under PowerShell: --dims "9.5,9,9,9"')
   .option('--json', 'Output as JSON')
   .action((feature, task, score, options) => scoreCommand(feature, task, score, options));
 
@@ -195,6 +197,12 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, newType, options) => retypeCommand(feature, newType, options));
 
+program
+  .command('handoff <feature>')
+  .description('Generate the compressed session-handoff document (.morph/features/{f}/handoff.md) — pointers, not copies')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => handoffCommand(feature, options));
+
 // ─── Tasks ────────────────────────────────────────────────────────────────
 program
   .command('dag <feature>')
@@ -321,6 +329,13 @@ worktreeCommand
   .option('--json', 'Output as JSON')
   .action((options) => worktreeListCommand(options));
 
+// ─── Fleet ────────────────────────────────────────────────────────────────
+program
+  .command('fleet')
+  .description('Fleet view — every active feature across primary root and worktrees (phase, gates, tasks, ports, handoff, activity)')
+  .option('--json', 'Output as JSON')
+  .action((options) => fleetCommand(options));
+
 // ─── Dashboard ────────────────────────────────────────────────────────────
 program
   .command('dashboard')

package/claude-plugin.json

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

@@ -99,16 +99,18 @@ morph-spec retype {feature} {newType}                    # change type mid-fligh
 
 ---
 
-## CLI — worktrees (parallel development)
+## CLI — worktrees (parallel development / fleet)
 
-One feature = one git worktree = one Claude Code instance. Independent features run side by side without stepping on each other's state; a SessionStart hook injects each worktree's feature identity into context.
+One feature = one git worktree = one Claude Code instance. Independent features run side by side without stepping on each other's state; a SessionStart hook injects each worktree's feature identity, allocated ports and handoff pointer into context. Each worktree gets a deterministic port block (`.morph/worktree.env`) and a regenerable handoff document.
 
 ```bash
 morph-spec create {feature} --worktree     # birth the feature already isolated in its own worktree
 morph-spec worktree setup {feature}        # create .worktrees/{feature}/ on branch morph/{feature}
 morph-spec worktree link [--all]           # relink shared infra (node_modules, .claude, .morph/framework)
-morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up (requires Gate 3)
+morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up + release ports (requires Gate 3)
 morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
+morph-spec handoff {feature} [--json]      # regenerate the compressed session-handoff doc (pointers, not copies)
+morph-spec fleet [--json]                  # fleet view: every active feature (root + worktrees) with phase/gates/ports/handoff/activity
 ```
 
 ---
@@ -237,4 +239,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v8.1.2 by Polymorphism Tech*
+*morph-spec v8.2.1 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -256,4 +256,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.1.2 by Polymorphism Tech*
+*morph-spec v8.2.1 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -6,7 +6,8 @@
 
 1. Leia `.morph/framework/MORPH.md` — o charter NLH com papéis, fases, gates e skills.
 2. Leia `.morph/state.json` — índice fino e gitignored (só status + updatedAt por feature) — para identificar a feature `in_progress` e a fase atual. **Não o edite à mão:** é reconstruído a partir dos `feature.json` a cada load. O estado autoritativo e commitado de cada feature vive em `.morph/features/{feature}/feature.json`.
-3. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.
+3. Se existir `.morph/features/{feature}/handoff.md` para a feature ativa, **leia-o antes de re-derivar contexto à mão** — é o documento de retomada (comprimido, aponta para os artefatos; regenere com `morph-spec handoff <f>` se parecer velho).
+4. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.
 
 Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
@@ -25,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
 
@@ -44,12 +45,14 @@ 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.
 - `morph-spec verify <feature> [task] [--json]` — cadeia determinística build+testes+validadores (código antes do juiz LLM); escopo de task quando informado, senão a feature inteira.
-- `morph-spec worktree setup|link|finish|list` — gerencia o ciclo do worktree por feature (`setup` cria `.worktrees/{f}/` na branch `morph/{f}`; `link` religa infra compartilhada; `finish` faz merge `--no-ff` e limpa; `list` mostra fase/gate de cada worktree ativo).
+- `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.
 
 ## Skills core (em `.claude/skills/`)
 
@@ -68,7 +71,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 Toda feature nasce com um `workType` (`morph-spec create <f> --type <tipo>` ou classificado de `--request "<pedido>"`) que dimensiona o pipeline: `feature` roda o fluxo completo (proposal → [uiux] → plan → implement → review); `bug` roda uma versão enxuta (proposal/plan lean); `chore` pula direto para implement (Gates 1/2 carimbados por política no nascimento); `hotfix` roda scout → fix cirúrgico → test loop → ship. O Gate 3 do `hotfix` **pausa sempre para um humano**, mesmo em `trust: auto` — o CLI recusa `morph-spec approve <f> review --mode auto` nesse tipo. Detalhes em `.morph/framework/MORPH.md` §2.1 e §5.
 
-Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --worktree` ou `morph-spec worktree setup <f>`) — uma feature por worktree, uma instância de Claude Code por worktree. `feature.json` viaja commitado na branch `morph/{f}`; ao fechar, aprove o Gate 3 dentro do worktree e rode `morph-spec worktree finish <f>` seguido de `morph-spec archive <f>` na raiz. Detalhes em `.morph/framework/MORPH.md` §2.2.
+Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --worktree` ou `morph-spec worktree setup <f>`) — uma feature por worktree, uma instância de Claude Code por worktree. Cada worktree tem seu **bloco de portas** próprio (`.morph/worktree.env` — suba dev servers SEMPRE nelas, nunca nas portas padrão) e seu **handoff.md** de retomada. `feature.json` viaja commitado na branch `morph/{f}`; ao fechar, aprove o Gate 3 dentro do worktree e rode `morph-spec worktree finish <f>` seguido de `morph-spec archive <f>` na raiz. Visão agregada: `morph-spec fleet`. Detalhes em `.morph/framework/MORPH.md` §2.2.
 
 ## Personas (em `.claude/agents/`)
 

package/framework/MORPH.md

@@ -112,14 +112,20 @@ Nem todo trabalho merece o pipeline completo. Cada feature nasce com um **workTy
 
 **Compat:** uma feature sem `workType` (criada antes do v8) é tratada como `feature`. Mudança de tipo mid-flight: `morph-spec retype <f> <tipo>` (desfaz só carimbos de política, preserva aprovações humanas; bloqueado após o Gate 3).
 
-### 2.2 Desenvolvimento paralelo por worktree
+### 2.2 Desenvolvimento paralelo por worktree (frota)
 
 Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu git worktree**, com uma instância de Claude Code por worktree. `morph-spec create <f> --worktree` (ou `morph-spec worktree setup <f>`) cria `.worktrees/{f}/` na branch `morph/{f}`. Contrato:
 
 - **Uma feature = um worktree = uma instância.** Nunca abra duas instâncias na mesma feature (o setup recusa com exit 3).
 - O estado autoritativo (`feature.json`) viaja **commitado na branch** `morph/{f}`. O `state.json` local do worktree é um índice derivável — materializado por self-heal, nunca sincronizado à mão.
 - Infra compartilhada (`node_modules`, `.claude`, `.morph/framework`) é linkada por junction; `memory/` e `logs/` são locais de cada worktree (isolamento correto). Se faltar infra num worktree (aberto com `git worktree add` puro), rode `morph-spec worktree link --all`.
-- **Fechamento:** aprove o Gate 3 dentro do worktree, depois `morph-spec worktree finish <f>` (merge `--no-ff` da branch na raiz primária limpa; recusa se worktree ou raiz estiverem sujos; aborta em conflito) e por fim `morph-spec archive <f>` na raiz. `morph-spec worktree list` mostra os worktrees ativos com fase e gate.
+- **Ambiente separado (portas):** o setup aloca um **bloco de portas determinístico** por feature e escreve `.morph/worktree.env` no worktree (`PORT`, `MORPH_PORT_RANGE`; `ASPNETCORE_URLS` quando o stack tem dotnet). **Suba dev servers SEMPRE nas portas do bloco** — as portas padrão (3000/5000) pertencem à raiz; duas instâncias no default se matam. O arquivo é local e git-invisível; o hook de SessionStart injeta as portas. Overrides em `config.json → fleet.basePort/blockSize`.
+- **Banco de dados:** worktrees compartilham o mesmo banco por padrão. Para isolamento real com o MCP do Neon disponível, crie um branch de DB `morph/{f}` e anote a connection string no `.morph/worktree.env` (a CLI nunca toca em credenciais); sem Neon, prefixe schema/DB local com o nome da feature. Migration destrutiva num worktree compartilhando banco → integre antes de abrir worktrees irmãos.
+- **Limitação conhecida:** `node_modules` é compartilhado (junction) — mudança de dependência feita num worktree afeta os irmãos. Mudou dependência: conclua e integre (`finish`) antes de seguir com worktrees paralelos.
+- **Handoff entre sessões:** `.morph/features/{f}/handoff.md` é o documento de retomada — comprimido, derivado e regenerável (`morph-spec handoff <f>`), ele **aponta** para os artefatos em vez de copiá-los. É regenerado automaticamente no `worktree setup`, `create --worktree` e `advance`; o hook de SessionStart aponta para ele. **Ao abrir uma sessão numa feature em andamento, leia o handoff antes de re-derivar contexto à mão.** Nunca o edite manualmente (é git-invisível e sobrescrito na próxima regeneração).
+- **Visão da frota:** `morph-spec fleet` agrega raiz + worktrees (fase, gates pendentes, tasks, portas, handoff, último commit, sujeira) — use entre sessões para decidir onde atuar. `morph-spec worktree list` continua sendo a visão enxuta por worktree.
+- **Ownership de arquivos:** não há lock em runtime, por design — a colisão de escrita se resolve **em plan-time** (`morph-spec dag` detecta overlap de `outputs` e recomenda `isolation: "worktree"`) e **por construção** (uma feature = um worktree = um escritor). Entre features, arquivos compartilhados convergem no merge do `finish` — conflito ali é o sinal honesto de escopo sobreposto, não um bug.
+- **Fechamento:** aprove o Gate 3 dentro do worktree, depois `morph-spec worktree finish <f>` (merge `--no-ff` da branch na raiz primária limpa; recusa se worktree ou raiz estiverem sujos; aborta em conflito; libera o bloco de portas) e por fim `morph-spec archive <f>` na raiz.
 
 ---
 
@@ -263,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/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/worktree-context.js

@@ -97,11 +97,54 @@ function featureFromSingleDir(dir) {
   }
 }
 
+/**
+ * Fleet env line: the worktree's allocated port block, read from the manifest
+ * `worktree setup` writes. Fail-open — a missing or malformed manifest just
+ * omits the line (the session then uses project defaults, which is exactly
+ * the pre-fleet behavior).
+ */
+function buildEnvLine(dir) {
+  try {
+    const envPath = join(dir, '.morph', 'worktree.env');
+    if (!existsSync(envPath)) return null;
+    const content = readFileSync(envPath, 'utf8');
+    const port = content.match(/^PORT=(\d+)$/m)?.[1];
+    if (!port) return null;
+    const range = content.match(/^MORPH_PORT_RANGE=([\d-]+)$/m)?.[1];
+    return `🔌 Ambiente desta worktree: PORT=${port}${range ? ` (bloco ${range})` : ''}. ` +
+      `Suba dev servers SEMPRE nessas portas (fonte: .morph/worktree.env) — as portas padrão pertencem à raiz.`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fleet handoff line: point the fresh session at the compressed handoff doc
+ * before it starts re-deriving context by hand. Fail-open.
+ */
+function buildHandoffLine(dir, feature) {
+  try {
+    const handoffPath = join(dir, '.morph', 'features', feature, 'handoff.md');
+    if (!existsSync(handoffPath)) return null;
+    const generatedAt = readFileSync(handoffPath, 'utf8')
+      .match(/gerado em (\d{4}-\d{2}-\d{2}T[\d:.]+Z)/)?.[1];
+    return `📄 Handoff: .morph/features/${feature}/handoff.md${generatedAt ? ` (gerado ${generatedAt})` : ''} — leia antes de continuar.`;
+  } catch {
+    return null;
+  }
+}
+
 function buildWorktreeContext(dir, feature) {
   const phase = getFeaturePhase(feature, dir);
   let text = `🌳 Worktree desta feature: ${feature} (branch morph/${feature}, fase ${phase}). ` +
     `Trabalhe apenas nesta feature nesta sessão; o estado vive no .morph/ deste worktree.`;
 
+  const envLine = buildEnvLine(dir);
+  if (envLine) text += `\n${envLine}`;
+
+  const handoffLine = buildHandoffLine(dir, feature);
+  if (handoffLine) text += `\n${handoffLine}`;
+
   const missingJunctions = !existsSync(join(dir, 'node_modules')) || !existsSync(join(dir, '.claude'));
   if (missingJunctions) {
     text += `\n⚠ Infra compartilhada ausente (node_modules/.claude). Rode: morph-spec worktree link --all`;

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/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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # 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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # 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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # 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)`.
@@ -177,7 +182,7 @@ Depois do batch paralelo, executar o restante em modo sequencial (passo 3a).
 
 Quando o `morph-spec dag {feature}` reporta `isolation.recommended: "worktree"` (dois fluxos paralelos planejam escrever no mesmo path — colisão de `outputs`), despache cada fluxo com o parâmetro `isolation: "worktree"` do tool Agent. Cada agente trabalha numa working tree própria; build/test rodam lá dentro sem colidir.
 
-1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. Se a stack for Node e faltar `node_modules` no worktree, o agente roda `morph-spec worktree link` (fail-open) antes de testar; se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). O agente commita na branch do worktree e reporta a branch.
+1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. Se a stack for Node e faltar `node_modules` no worktree, o agente roda `morph-spec worktree link` (fail-open) antes de testar; se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). Se o agente precisar subir um dev server e existir `.morph/worktree.env` no seu cwd, usa as portas de lá (nunca as padrão — MORPH.md §2.2). O agente commita na branch do worktree e reporta a branch.
 2. **Integração (orquestrador, após todos os relatórios):** faça o merge de cada branch reportada, uma por vez, na ordem de chegada — `git merge --no-ff <branch>`. Conflito → `git merge --abort`, marque a task de volta a `pending` com nota "merge conflict — reexecutar sequencial", siga para a próxima branch. Os paths em conflito são exatamente os de `isolation.collisions` do dag.
 3. **Pós-merge:** rode `morph-spec verify {feature} --json` UMA vez (o merge é o novo ponto de integração — verificação compartilhada obrigatória), depois `morph-eval` + `morph-spec score` por relatório, como em §3b.
 4. **Cleanup:** `git worktree remove` + `git branch -d` das branches integradas + `git worktree prune` (fail-open). Branches não integradas ficam e são registradas no recap com o motivo.

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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # 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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # 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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # morph-hotfix

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

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

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

@@ -4,7 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.1.2"
+cliVersion: "8.2.1"
 ---
 
 # morph-plan

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.1.2"
+cliVersion: "8.2.1"
 ---
 
 # morph-proposal

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.1.2"
+cliVersion: "8.2.1"
 ---
 
 # morph-review
@@ -56,18 +56,22 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          seguindo as bandas 0-10 de cada uma.
          NÃO reescreva código. NÃO toque em tasks.json, feature.json nem no board
          de sessão.
-         Contrato do relatório final — ATO FINAL: o seu relatório é a sua
-         ÚLTIMA MENSAGEM DE TEXTO; ela é o valor de retorno desta sessão e
-         chega inteira ao orquestrador. NÃO chame SendMessage: ele gera um
-         evento a mais além da notificação de término, custando um turno
-         inútil ao orquestrador. Escreva o relatório e encerre.
-         Seu relatório final deve conter: score 0-10 por dimensão, score
-         composto (arch×0.30 + contracts×0.25 + quality×0.25 + tests×0.20), e
-         feedback priorizado (bloqueantes primeiro) para qualquer dimensão < 9.
-         Relatório oco, ou sem esses itens, é falha de protocolo.
+         Contrato do relatório final: GRAVE seu relatório em
+         `.morph/features/{feature}/4-review/evaluator-report.md` ANTES de
+         encerrar — esse arquivo é o valor de retorno autoritativo desta
+         sessão. A sua última mensagem de texto é cortesia best-effort: pode
+         não chegar inteira ao orquestrador (o evento recebido às vezes é só
+         um idle_notification, sem texto). Ainda assim NÃO chame SendMessage:
+         ele gera um evento a mais além da notificação de término, custando
+         um turno inútil ao orquestrador.
+         Seu relatório (no arquivo, e na mensagem final quando ela chega)
+         deve conter: score 0-10 por dimensão, score composto (arch×0.30 +
+         contracts×0.25 + quality×0.25 + tests×0.20), e feedback priorizado
+         (bloqueantes primeiro) para qualquer dimensão < 9. Relatório
+         ausente, oco, ou sem esses itens, é falha de protocolo.
      ```
    - **Fallback (tipo não registrado):** se `morph-evaluator` não estiver na sua lista de subagent types, despache `general-purpose` colando o campo `persona` do agente `evaluator` (Read em `.morph/framework/agents.json`) no topo do prompt — e **registre o fallback no review-report** (seção de método).
-   - Os scores por dimensão e o composto do review-report vêm **desse retorno**, não da sua auto-avaliação. Se o relatório vier oco ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
+   - **Leia primeiro** `.morph/features/{feature}/4-review/evaluator-report.md` — é o valor de retorno autoritativo, não a mensagem de texto do dispatch (que é cortesia, útil só quando chega inteira). Os scores por dimensão e o composto do review-report vêm **desse arquivo**, não da sua auto-avaliação. Se o arquivo vier ausente, oco, ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
@@ -117,7 +121,10 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
 ## Output esperado
-- `.morph/features/{feature}/4-review/review-report.md` com scores e recomendação
+- `.morph/features/{feature}/4-review/evaluator-report.md` — relatório bruto e autoritativo do
+  `morph-evaluator` despachado no passo 4 (canal durável, ver MORPH.md §6)
+- `.morph/features/{feature}/4-review/review-report.md` — síntese do orquestrador a partir do
+  evaluator-report, com scores e recomendação
 - Trace da fase com `phase_summary` preenchido
 - Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo), na forma canônica `{ approved, timestamp, approvedBy }` — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual