@polymorphism-tech/morph-spec 8.15.0 → 8.16.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:** 8.15.0  
+**Version:** 8.16.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.15.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.16.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -63,6 +63,7 @@ import { dashboardCommand } from '../src/commands/dashboard/dashboard.js';
 
 // === Observability ===
 import { telemetryCommand } from '../src/commands/observability/telemetry.js';
+import { costCommand } from '../src/commands/observability/cost.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -404,4 +405,11 @@ program
   .option('--limit <n>', 'How many recent prompts to show (default 10)', (v) => parseInt(v, 10))
   .action((options) => telemetryCommand(options));
 
+program
+  .command('cost [feature]')
+  .description('Cost-facing view over .morph/logs/events.jsonl: task duration, bytes re-ingested by kind (proxy, not tokens), dispatch counts')
+  .option('--by <mode>', 'Group by: task|phase (default: feature-wide summary)')
+  .option('--json', 'Output the aggregate as JSON')
+  .action((feature, options) => costCommand(feature, options));
+
 program.parse();

package/claude-plugin.json

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

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.15.0 by Polymorphism Tech*
+*morph-spec v8.16.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.15.0 by Polymorphism Tech*
+*morph-spec v8.16.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -44,7 +44,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `/morph-troubleshoot [erro]` | Diagnóstico de erros .NET/Next.js com root-cause analysis |
 
 **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`. **O Gate 3 exige `4-review/evaluator-report.md`**: sem o relatório do avaliador independente o comando recusa (exit 1). Se o dispatch do avaliador for impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` **não** dispensa esta regra (é só para ordem de gate).
+- `morph-spec approve <feature> <gate> --mode auto` — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`. **O Gate 3 exige `4-review/evaluator-report.md`**: sem o relatório do avaliador independente o comando recusa (exit 1). Se o dispatch do avaliador for impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` **não** dispensa esta regra (é só para ordem de gate). **Exceção `hotfix`:** esse tipo nunca despacha o avaliador (`morph-hotfix` §7); o Gate 3 exige `4-review/review-report.md` no lugar do `evaluator-report.md`, e a assinatura humana continua obrigatória via `--approver` (o backstop de `--mode auto` acima permanece recusando).
 - `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-**sem-integrar** (atômico, git-aware, commita o move escopado por pathspec): reservado a features legadas (sem branch `morph/{f}`) e faxina. O fechamento normal (arquiva **e** integra num passo) é `morph-spec finish`. É o que `/morph-archive` chama.
 - `morph-spec finish <feature> --pr|--merge` — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — promovendo junto, no mesmo commit, os use cases da feature para o acervo permanente `.morph/specs/usecases/` com `status: implemented` (fail-open: sem `2-plan/usecases/`, no-op silencioso) — depois integra. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados.
@@ -63,6 +63,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `morph-spec report-check <feature> [task] [--json]` — audita os relatórios de sub-agent contra o trabalho que realmente entrou. **Relatório ausente NÃO quer dizer que o agente falhou** — ele pode ter feito tudo e perdido o meio de gravar. O comando responde a pergunta certa (`work-landed-report-missing` → aceite degradado, NÃO re-despache; `no-work-no-report` → re-despache uma vez). Protocolo completo em MORPH.md §6.
 - `morph-spec claim [feature] [--release] [--list] [--json]` — posse **advisory** de feature. Cada sessão reclama sua feature ativa automaticamente (hook SessionStart) e renova o heartbeat a cada tool call; o registro vive em `<git-common-dir>/morph-spec/claims.json`, compartilhado por todos os worktrees. **`morph-spec claim <feature>` (sem flags) ADQUIRE** — se esta árvore já tinha claim vivo em outra feature, ele é liberado no mesmo passo (o CLI reporta "movido de X para Y"); é o jeito de trocar de feature no meio da tarefa sem o dança de dois passos `--release` + reclamar. `--list` força a leitura sem adquirir mesmo passando uma feature. **Claims avisam, nunca bloqueiam** — mas se o SessionStart avisar que outra sessão tem claim vivo, **confirme antes de `finish`/`archive`/`delete`**: duas sessões na mesma feature já custaram um recap.md inteiro e um sub-agent (o worktree sumiu debaixo dele). Claim órfão de sessão morta: `morph-spec claim <f> --release`.
 - `morph-spec telemetry [--json] [--feature <f>] [--limit <n>]` — reconstrói o caminho de execução da sessão a partir de `.morph/logs/events.jsonl` (skills invocadas, personas despachadas + prompts, standards/base de conhecimento lidos, mix de tools, prompts do usuário). Capturado silenciosamente pelo hook `telemetry-log` em todo tool call e todo UserPromptSubmit.
+- `morph-spec cost [feature] [--by task|phase] [--json]` — custo da execução a partir do mesmo `events.jsonl`: duração por task (TaskStart→TaskEnd), bytes de contexto re-ingerido por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code`), dispatches + tamanho de prompt e mix de tools. Bytes re-ingeridos são **proxy determinística** de custo de token (tokens reais não são observáveis por hook). Use antes/depois de mudar skill ou fluxo para medir o efeito.
 
 ## Skills core (em `.claude/skills/`)
 

package/framework/MORPH.md

@@ -75,7 +75,7 @@ Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durant
 
 **Evaluator** — ativo após uma tarefa ou fase ser concluída.
 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. **A regra é enforced server-side:** `morph-spec approve {feature} review` recusa (exit 1) enquanto `4-review/evaluator-report.md` não existir. Se o dispatch for genuinamente impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` não dispensa a regra (é só para ordem de gate).
+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. **A regra é enforced server-side:** `morph-spec approve {feature} review` recusa (exit 1) enquanto `4-review/evaluator-report.md` não existir. Se o dispatch for genuinamente impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` não dispensa a regra (é só para ordem de gate). **Exceção `hotfix`:** o tipo nunca despacha o avaliador (velocidade é o ponto do hotfix); o Gate 3 exige `4-review/review-report.md` — o artefato que a `morph-hotfix` de fato produz — e a assinatura humana continua obrigatória (§2.1/§5), sem afrouxar nada para os demais tipos.
 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.
@@ -125,6 +125,7 @@ Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu gi
 - **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`.
+- **Nunca apague um worktree à mão** (`rm -rf`, `Remove-Item -Recurse -Force`, deletar a pasta pelo explorador/IDE). O `morph-spec finish`/`worktree remove` desmonta a junction ANTES de remover (PROVE-or-DECLINE — nunca segue o link para fora); um `rm -rf`/`Remove-Item -Recurse` genérico não sabe disso e, em muitas implementações (inclusive o `Remove-Item -Recurse` do PowerShell no Windows), atravessa a junction e apaga o conteúdo real da raiz que ela aponta — o `.claude`/`node_modules`/`.morph/framework` compartilhados, não só o link. Se um worktree precisa sumir, use sempre `morph-spec finish <f> --pr|--merge` (ou, sem fechar a feature, `git worktree remove`, nunca uma remoção de diretório genérica).
 - **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.
@@ -245,7 +246,7 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), gates **
 - Sinais: `evalScore` composite, `standardsViolations` detectadas em implementation.
 - Skill responsável: `morph-review`.
 
-**Gates por tipo de trabalho:** `chore` e `hotfix` não passam pelos Gates 1 e 2 — eles são carimbados por política no nascimento (`approvedBy: "policy:{tipo}"`, nunca `"auto"`, para não colidir com o gate-guard). A barra de qualidade do morph-eval e o Gate 3 continuam valendo para todos os tipos. Para `hotfix`, o Gate 3 é **sempre humano**: mesmo em `trust: auto` a `morph-hotfix` apresenta o review via `AskUserQuestion` e o `risk-detector` força a pausa; o backstop server-side (`morph-spec approve ... review --mode auto` recusa) garante que nenhum caminho auto passe por cima.
+**Gates por tipo de trabalho:** `chore` e `hotfix` não passam pelos Gates 1 e 2 — eles são carimbados por política no nascimento (`approvedBy: "policy:{tipo}"`, nunca `"auto"`, para não colidir com o gate-guard). A barra de qualidade do morph-eval e o Gate 3 continuam valendo para todos os tipos. Para `hotfix`, o Gate 3 é **sempre humano**: mesmo em `trust: auto` a `morph-hotfix` apresenta o review via `AskUserQuestion` e o `risk-detector` força a pausa; o backstop server-side (`morph-spec approve ... review --mode auto` recusa) garante que nenhum caminho auto passe por cima. O artefato exigido também difere: `hotfix` nunca despacha o avaliador independente, então o Gate 3 exige `4-review/review-report.md` em vez de `evaluator-report.md`; todos os outros tipos continuam exigindo o `evaluator-report.md` (ou `--self-assessed` registrado).
 
 Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `"manual"`). Configs sem o campo `trust` defaultam para `"auto"`.
 
@@ -401,4 +402,4 @@ Nenhuma skill deve ser invocada proativamente por um hook ou script automático.
 > Alterações de comportamento do harness exigem atualização aqui, não em hooks ou scripts.
 > Versão inicial criada em 2026-04-24. Próxima revisão recomendada após o ciclo completo com NLH.
 >
-> Para histórico de decisões sobre este documento, consulte os commits do arquivo e o `harness-token-audit.md` na raiz do repositório.
+> Para histórico de decisões sobre este documento, consulte os commits do arquivo.

package/framework/hooks/README.md

@@ -46,15 +46,15 @@ framework/hooks/
 | **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) | 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) | post-edit-typecheck.js | Advisory | Debounced `tsc --noEmit` after TS/TSX edits; silent on success. Also touches `.morph/memory/build-dirty.json` on every source-file edit — the write side of validate-completion.js's Stop-hook build-dirty gate |
 | **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** (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.jsonl` (issue #63) |
 | **PostToolUse** (all tools) | telemetry-log.js | Telemetry | Appends every tool call (skill, sub-agent dispatch + prompt, knowledge-base read, bash/edit) to `.morph/logs/events.jsonl`; silent, fail-open — the NLH execution-path capture read back by `morph-spec telemetry` |
 | **PostToolUse** (all tools) | loop-detect.js | Advisory | Warns when the last 8 actions collapse to ≤2 unique signatures |
 | **UserPromptSubmit** | telemetry-log.js | Telemetry | Appends the user's prompt to the same `events.jsonl` stream; silent, fail-open |
-| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift; build check; session snapshot |
+| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift (hash-deduped, only re-injects when the warning set changes); dirty-flag-gated build check |
 
 ## Design Principles
 

package/framework/hooks/claude-code/core/chain.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * chain.js — roda vários hooks core num único processo node.
+ *
+ * Motivação (onda de performance R2): cada hook registrado no Claude Code é
+ * hoje um processo node próprio (~60ms de cold start). Um único Write/Edit
+ * disparava até 9 desses processos — 2 PreToolUse + 3+2+2 PostToolUse. Este
+ * script agrupa os elos de um mesmo event+matcher (a mesma entrada do
+ * registry em src/utils/hooks-installer.js) num só spawn: lê stdin UMA vez,
+ * importa e chama `run(payload)` de cada hook em sequência, e combina as
+ * respostas — reduzindo esses 9 spawns para 4 por Write/Edit (1 PreToolUse +
+ * 3 PostToolUse: Write|Edit / Write|Edit|AskUserQuestion / matcher-`*`).
+ *
+ * Uso: `node chain.js <hook1> <hook2> ...` — nomes de arquivo SEM `.js`,
+ * resolvidos no mesmo diretório deste script (core/), na ORDEM em que devem
+ * rodar. A ordem é a mesma que o registry antigo (duas entries separadas)
+ * já implicava — ver o comentário de cada grupo em hooks-installer.js.
+ *
+ * Cada hook core exporta `run(payload)` (ver framework/hooks/shared/hook-response.js
+ * `runStandalone`) — o arquivo continua executável standalone (spawnSync
+ * direto, como os testes já fazem) porque a própria cauda do arquivo só lê
+ * stdin/imprime/sai quando NÃO está sendo importado por esta cadeia.
+ *
+ * Regras de combinação:
+ *  - PreToolUse (decision:'block'): o PRIMEIRO elo que retornar um bloqueio
+ *    VENCE e encerra a cadeia — os elos seguintes nem chegam a rodar. Isto é
+ *    uma otimização NOVA desta consolidação (antes, Claude Code podia
+ *    disparar os dois processos de qualquer forma); o resultado observável
+ *    pro Claude Code é idêntico (o tool call é bloqueado do mesmo jeito).
+ *  - PostToolUse / outros eventos de contexto: os textos de TODOS os elos que
+ *    retornarem `hookSpecificOutput.additionalContext` (ou `decision:'approve'`
+ *    com additionalContext) são concatenados, na ORDEM dos argv, separados por
+ *    uma linha em branco — nenhum elo é pulado por um vizinho ter respondido.
+ *  - Nome do evento (hookSpecificOutput.hookEventName) no resultado final:
+ *    o valor que o PRIMEIRO elo a declarar um venceu (mesma regra de
+ *    "primeiro vence" do bloqueio acima — na prática todos os elos de um
+ *    mesmo grupo observam o MESMO evento real do Claude Code, então isto só
+ *    importa como desempate determinístico); na ausência de qualquer elo
+ *    declarando, cai para `payload.hook_event_name`; por último, `'PostToolUse'`.
+ *  - Fail-open POR ELO: uma exceção não tratada por um hook individual (import
+ *    falhou, run() não existe, etc.) não derruba a cadeia — os elos seguintes
+ *    ainda rodam. Cada hook já fail-opens sozinho dentro do seu próprio
+ *    try/catch; isto é a segunda rede de segurança, para o import em si.
+ */
+
+import { dirname, join } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { readStdin } from '../../shared/stdin-reader.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Marca "já estou dentro de uma cadeia" para os hooks importados abaixo: a
+// cauda de execução standalone de cada hook (runStandalone() em
+// hook-response.js) só dispara quando esta flag NÃO está setada. Setada
+// ANTES do primeiro import dinâmico — cada hook importado herda o mesmo
+// process.env deste processo.
+process.env.MORPH_HOOK_CHAINED = '1';
+
+// Override só para testes da mecânica genérica desta cadeia (fixtures fora
+// de core/, sem precisar ser hooks reais nem satisfazer as convenções que
+// hook-wiring.test.js exige de todo arquivo em core/). Produção nunca seta
+// isto — resolve sempre no próprio diretório deste script.
+const coreDir = process.env.MORPH_HOOK_CORE_DIR || __dirname;
+
+/** Extrai o texto de contexto de um resultado de hook, se houver. */
+function contextOf(result) {
+  if (!result) return null;
+  if (result.decision === 'approve' && typeof result.additionalContext === 'string') {
+    return result.additionalContext;
+  }
+  const ctx = result?.hookSpecificOutput?.additionalContext;
+  return typeof ctx === 'string' && ctx ? ctx : null;
+}
+
+async function main() {
+  const names = process.argv.slice(2);
+  const payload = await readStdin();
+
+  const contexts = [];
+  let eventName = null;
+
+  for (const name of names) {
+    let result = null;
+    try {
+      const mod = await import(pathToFileURL(join(coreDir, `${name}.js`)).href);
+      result = await mod.run(payload);
+    } catch {
+      // Fail-open POR ELO — ver doc do módulo acima.
+      result = null;
+    }
+
+    if (!result) continue;
+
+    // PreToolUse: o primeiro bloqueio vence e encerra a cadeia.
+    if (result.decision === 'block') {
+      console.log(JSON.stringify(result));
+      process.exit(0);
+    }
+
+    const ctx = contextOf(result);
+    if (ctx) {
+      contexts.push(ctx);
+      // First link to declare a name wins (mirrors block-first-wins above) —
+      // in practice every link in a group observes the SAME real Claude Code
+      // event, so this only matters as a deterministic tie-break.
+      eventName = eventName || result?.hookSpecificOutput?.hookEventName;
+    }
+  }
+
+  if (contexts.length === 0) {
+    process.exit(0);
+  }
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName || payload?.hook_event_name || 'PostToolUse',
+      additionalContext: contexts.join('\n\n'),
+    },
+  }));
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -18,7 +18,6 @@
  */
 
 import { existsSync } from 'fs';
-import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, getFeaturePhase, isGateApproved } from '../../shared/state-reader.js';
 import {
   isFeaturePath,
@@ -40,88 +39,96 @@ const PHASE_DIR_ENTRY_GATE = {
   '3-implement': 'plan',
   '4-review': 'plan',
 };
-import { block, pass } from '../../shared/hook-response.js';
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 
-try {
-  // Amend mode: bypass phase write enforcement for legitimate corrections
-  if (process.env.MORPH_AMEND_PHASE) {
-    console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
-    pass();
-  }
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
-
-  // Only check files inside .morph/features/
-  if (!isFeaturePath(filePath)) pass();
-
-  // Resolve the tree that OWNS this file, NOT the tree the session sits in.
-  // A session rooted in the primary repo may legitimately write to a feature
-  // living in a secondary worktree; reading the session's `.morph/` there
-  // reported the ROOT's phase for the WORKTREE's file, and blocked a legal
-  // `2-plan/` write with "not allowed during PROPOSAL phase". `stateExists`
-  // must be asked of that same tree — a worktree carries its own state.
-  const root = resolveMorphRoot(filePath, process.cwd());
-  if (!stateExists(root)) pass();
-
-  const featureName = extractFeatureName(filePath);
-  if (!featureName) pass();
-
-  const phase = getFeaturePhase(featureName, root);
-  if (!phase) pass();
-
-  // During implement phase, all writes are allowed (source code is unrestricted)
-  if (phase === 'implement' || phase === 'sync') pass();
-
-  const targetDir = extractPhaseDir(filePath);
-  if (!targetDir) pass(); // File directly in feature root — allow
-
-  const allowedDir = PHASE_DIRS[phase];
-  if (!allowedDir) pass(); // Unknown phase — allow
-
-  if (targetDir !== allowedDir) {
-    // Allow editing already-existing files from previous phases
-    const absolutePath = resolveTargetPath(filePath, root);
-    if (existsSync(absolutePath)) {
-      logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-      pass(); // editing existing file — allow
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload
+ * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
+ *   Never prints, never exits — see runStandalone()/chain.js at the bottom.
+ */
+export async function run(payload) {
+  try {
+    // Amend mode: bypass phase write enforcement for legitimate corrections
+    if (process.env.MORPH_AMEND_PHASE) {
+      console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+      return null;
     }
 
-    // Gate-aware forward transition: allow creating the NEXT phase's first
-    // artifact as soon as the gate authorizing that phase is approved. Without
-    // this, the first file of a new phase can never be written (the phase only
-    // advances once that file exists) — the deadlock this hook used to create.
-    const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
-    if (entryGate && isGateApproved(featureName, entryGate, root)) {
-      logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-      pass();
+    if (!payload) return null;
+
+    const filePath = getFilePath(payload);
+    if (!filePath) return null;
+
+    // Only check files inside .morph/features/
+    if (!isFeaturePath(filePath)) return null;
+
+    // Resolve the tree that OWNS this file, NOT the tree the session sits in.
+    // A session rooted in the primary repo may legitimately write to a feature
+    // living in a secondary worktree; reading the session's `.morph/` there
+    // reported the ROOT's phase for the WORKTREE's file, and blocked a legal
+    // `2-plan/` write with "not allowed during PROPOSAL phase". `stateExists`
+    // must be asked of that same tree — a worktree carries its own state.
+    const root = resolveMorphRoot(filePath, process.cwd());
+    if (!stateExists(root)) return null;
+
+    const featureName = extractFeatureName(filePath);
+    if (!featureName) return null;
+
+    const phase = getFeaturePhase(featureName, root);
+    if (!phase) return null;
+
+    // During implement phase, all writes are allowed (source code is unrestricted)
+    if (phase === 'implement' || phase === 'sync') return null;
+
+    const targetDir = extractPhaseDir(filePath);
+    if (!targetDir) return null; // File directly in feature root — allow
+
+    const allowedDir = PHASE_DIRS[phase];
+    if (!allowedDir) return null; // Unknown phase — allow
+
+    if (targetDir !== allowedDir) {
+      // Allow editing already-existing files from previous phases
+      const absolutePath = resolveTargetPath(filePath, root);
+      if (existsSync(absolutePath)) {
+        logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+        return null; // editing existing file — allow
+      }
+
+      // Gate-aware forward transition: allow creating the NEXT phase's first
+      // artifact as soon as the gate authorizing that phase is approved. Without
+      // this, the first file of a new phase can never be written (the phase only
+      // advances once that file exists) — the deadlock this hook used to create.
+      const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
+      if (entryGate && isGateApproved(featureName, entryGate, root)) {
+        logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+        return null;
+      }
+
+      const phaseLabel = phase.toUpperCase();
+      // Name the tree the verdict came from whenever it is NOT the session's own.
+      // The phase read is per-tree, so "which .morph/ said proposal?" is the first
+      // question anyone debugging this asks.
+      const treeNote = root !== process.cwd().replace(/\\/g, '/')
+        ? `\n(phase read from the tree that owns the file: ${root})`
+        : '';
+      logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
+      return blockResult(
+        `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
+        `Current phase '${phase}' only permits writes to '${allowedDir}/'.${treeNote}\n\n` +
+        `To move forward, approve the current gate and scaffold the next phase in\n` +
+        `one step:  morph-spec advance ${featureName}\n` +
+        `(run it in that tree — the gate is recorded in its own feature.json).`
+      );
     }
 
-    const phaseLabel = phase.toUpperCase();
-    // Name the tree the verdict came from whenever it is NOT the session's own.
-    // The phase read is per-tree, so "which .morph/ said proposal?" is the first
-    // question anyone debugging this asks.
-    const treeNote = root !== process.cwd().replace(/\\/g, '/')
-      ? `\n(phase read from the tree that owns the file: ${root})`
-      : '';
-    logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
-    block(
-      `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
-      `Current phase '${phase}' only permits writes to '${allowedDir}/'.${treeNote}\n\n` +
-      `To move forward, approve the current gate and scaffold the next phase in\n` +
-      `one step:  morph-spec advance ${featureName}\n` +
-      `(run it in that tree — the gate is recorded in its own feature.json).`
-    );
+    logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+    return null;
+  } catch {
+    // Fail-open
+    return null;
   }
-
-  logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
 }
+
+await runStandalone(run);

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

@@ -24,21 +24,12 @@
  * No persisted decision, non-gate action, or any error → silence.
  */
 
-import { readFileSync } from 'fs';
 import { loadState, stateExists, getActiveFeature } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { locateFeatureForQuestion } from '../../shared/feature-locator.js';
 
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
@@ -118,7 +109,7 @@ function checkAskUserQuestion(input, sessionRoot) {
     if (!decision) continue; // no persisted decision → nothing to verify
     if (decision.pause === false) {
       logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
-      return injectContext(
+      return contextResult(
         `⚠️ [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 ` +
         `(trust:${decision.trust ?? 'auto'}, nenhum sinal de risco). ` +
@@ -130,9 +121,9 @@ function checkAskUserQuestion(input, sessionRoot) {
     }
     // The decision said pause:true and the LLM did pause — coherent.
     logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
-    return pass();
+    return null;
   }
-  return pass();
+  return null;
 }
 
 /** True for edits to .morph/state.json (legacy) or a per-feature feature.json (v5). */
@@ -149,17 +140,17 @@ function isGateStateFile(filePath) {
  */
 function checkStateEdit(input, sessionRoot) {
   const filePath = input.tool_input?.file_path;
-  if (!isGateStateFile(filePath)) return pass();
+  if (!isGateStateFile(filePath)) return null;
 
   // The edited file names its own tree — and, for the v5 per-feature
   // feature.json, its own feature. Only the legacy `.morph/state.json` shape
   // still needs a most-recently-updated fallback within that tree.
   const cwd = rootOfGateStateFile(filePath, sessionRoot);
-  if (!stateExists(cwd)) return pass(); // fail-open
+  if (!stateExists(cwd)) return null; // fail-open
   const state = loadState(cwd);
-  if (!state) return pass();
+  if (!state) return null;
   const feature = featureFromStatePath(filePath) || getActiveFeature(cwd)?.name;
-  if (!feature) return pass();
+  if (!feature) return null;
 
   let checked = false;
   const gates = state.features?.[feature]?.approvalGates ?? {};
@@ -171,7 +162,7 @@ function checkStateEdit(input, sessionRoot) {
     if (!decision) continue;
     if (decision.pause === true) {
       logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
-      return injectContext(
+      return contextResult(
         `⚠️ [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'}). ` +
@@ -183,24 +174,29 @@ function checkStateEdit(input, sessionRoot) {
     checked = true;
   }
   if (checked) logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
-  return pass();
+  return null;
 }
 
-function main() {
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
+ * @returns {Promise<object|null>} a hookSpecificOutput warning on a
+ *   trust-mode divergence, or null (pass/silent).
+ */
+export async function run(payload) {
   // Starting point only — each branch resolves the tree it actually inspects
   // (from the edited path, or from the feature the question names).
   const sessionRoot = projectDir();
 
-  const input = readStdin();
+  const input = payload || {};
   const toolName = input.tool_name;
 
   // 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') {
-    if (!isGateStateFile(input.tool_input?.file_path)) return pass();
+    if (!isGateStateFile(input.tool_input?.file_path)) return null;
   } else if (toolName !== 'AskUserQuestion') {
-    return pass();
+    return null;
   }
 
   try {
@@ -209,7 +205,7 @@ function main() {
   } catch {
     // fail-open
   }
-  return pass();
+  return null;
 }
 
-main();
+await runStandalone(run);