@polymorphism-tech/morph-spec 8.15.1 → 8.17.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.1  
+**Version:** 8.17.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.1 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.17.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -26,6 +26,7 @@ import { statusCommand } from '../src/commands/project/status.js';
 import { worktreeSetupCommand, worktreeLinkCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
 import { fleetCommand } from '../src/commands/project/fleet.js';
 import { claimCommand } from '../src/commands/project/claim.js';
+import { standardsCommand } from '../src/commands/project/standards.js';
 import { reportCheckCommand } from '../src/commands/state/report-check.js';
 
 // === Approval gates (human-only) ===
@@ -63,6 +64,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'));
@@ -380,6 +382,16 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, options) => claimCommand(feature, options));
 
+// ─── Standards search (server-side, R2 token cut) ─────────────────────────
+program
+  .command('standards')
+  .description('Search STANDARDS.json server-side (top 3, full digest) instead of reading the whole registry. No --find: list categories + counts')
+  .option('--find <query>', 'Search query — matches name/id, tags/aliases, category, digest')
+  .option('--category <category>', 'Restrict --find to a single category')
+  .option('--tags <tags>', 'Restrict --find to standards carrying any of these comma-separated tags')
+  .option('--json', 'Output as JSON')
+  .action((options) => standardsCommand(options));
+
 // ─── Sub-agent report protocol ────────────────────────────────────────────
 program
   .command('report-check <feature> [task]')
@@ -404,4 +416,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.1",
+  "version": "8.17.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.1 by Polymorphism Tech*
+*morph-spec v8.17.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.15.1 by Polymorphism Tech*
+*morph-spec v8.17.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -15,10 +15,10 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 **NUNCA:**
 - Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
-- Modificar o contrato do plano depois do Gate 2: `spec.md`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) estão congelados. **Os use cases (`2-plan/usecases/UC-*.md`) NÃO estão** — são editáveis por design, é assim que se muda o comportamento e se re-roda `implement`; a auditoria fica no git.
+- Modificar o contrato do plano depois do Gate 2: `spec.md`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`, `agent`, `standards`) estão congelados. **Os use cases (`2-plan/usecases/UC-*.md`) NÃO estão** — são editáveis por design, é assim que se muda o comportamento e se re-roda `implement`; a auditoria fica no git.
 - Escrever critérios de aceite no `proposal.md`. O comportamento verificável mora nos use cases, cuja pós-condição precisa ser **observável em teste** e chega **literal** ao `doneCriteria` da task.
 - Editar `.morph/specs/usecases/` à mão. O acervo só se escreve pela promoção do `finish`, que lê de `2-plan/usecases/` — é ela que carimba `status: implemented` e sobrescreve por ID. Para mudar um UC existente (o caso `bug`), copie-o para o `2-plan/usecases/` da feature e corrija lá.
-- Tocar os campos de contrato do plano em `tasks.json` após o Gate 2 (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) — o hook `protect-spec-files` faz diff semântico e bloqueia mudanças neles, seja via `Write` ou `Edit`. (Os campos mutáveis `status`/`outputs`/`notes` continuam graváveis por `Write` ou `Edit` — ver SEMPRE.)
+- Tocar os campos de contrato do plano em `tasks.json` após o Gate 2 (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`, `agent`, `standards`) — o hook `protect-spec-files` faz diff semântico e bloqueia mudanças neles, seja via `Write` ou `Edit`. (Os campos mutáveis `status`/`outputs`/`notes` continuam graváveis por `Write` ou `Edit` — ver SEMPRE.)
 - Listar perguntas em texto simples — sempre use a tool `AskUserQuestion` (1-4 perguntas por chamada).
 - Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), ou SQL cru sem justificativa.
 
@@ -29,7 +29,12 @@ 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. **A pergunta PRECISA nomear a feature** ("Gate 2 — Plano de {feature} aprovado?"): é por esse nome que o hook `state-sync` atribui a aprovação ao `feature.json` certo, na árvore certa. Sem nome, e havendo mais de uma feature na árvore, ele **recusa a gravar** e avisa — adivinhar já carimbou um Gate 2 na feature errada. Nesse caso aprove com `morph-spec approve <feature> <gate>`.
 - 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 (**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.
+- **Contrato do relatório final** em todo dispatch de sub-agent:
+  1. Grava o relatório em arquivo canônico ANTES de encerrar — `.morph/features/{f}/3-implement/reports/{taskId}.md` (avaliador: `4-review/evaluator-report.md`) — com os 4 itens obrigatórios (o quê / arquivos / problemas / auto-score 0-10). Esse arquivo é o retorno autoritativo, não a mensagem final; nunca chamar `SendMessage`.
+  2. Não tocar `tasks.json`/`feature.json`/`state.json` nem o board de sessão — estado é do orquestrador.
+  3. Sem build/test da suíte compartilhada em batch paralelo sem isolamento (verificação é do orquestrador, pós-batch).
+
+  Racional completo: `MORPH.md` §6. Templates curtos: `morph-implement` §4, `morph-apply` §3b. **O orquestrador lê o arquivo ao retomar controle** — nunca confia só na mensagem de retorno da tool.
 
 ## Slash commands
 
@@ -44,7 +49,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 +68,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.
@@ -199,7 +199,7 @@ O índice de standards fica em `framework/standards/STANDARDS.json`. Cada entrad
 
 **Fluxo de consulta:**
 
-1. Antes de iniciar uma tarefa, identifique de 1 a 3 standards relevantes pelo `id` ou `tags`.
+1. Antes de iniciar uma tarefa, identifique de 1 a 3 standards relevantes — rode `morph-spec standards --find "<domínio/tecnologia da task>"` (o comando devolve o top 3 como `id · path · digest`, sem você abrir o índice inteiro) em vez de filtrar `id`/`tags` à mão no JSON.
 2. Leia apenas o arquivo `.md` daquele standard específico — o path está no campo `path` do JSON.
 3. Aplique o standard durante a implementação. Se precisar de contexto adicional, leia mais um standard.
 4. Registre no recap.md qual standard foi consultado e como foi aplicado.
@@ -246,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"`.
 
@@ -402,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/evals/rubrics/condensed.md

@@ -0,0 +1,49 @@
+# Rubrica Condensada — Eval Inline por Task
+
+Versão compacta das 4 rubricas completas de `framework/evals/rubrics/`, para o eval
+**inline por task** (`morph-eval` §2, escopo tarefa única). Mesmas dimensões, mesmos
+pesos, mesma régua — só menos texto por banda.
+
+> **O Gate 3 NÃO usa esta condensada.** O avaliador independente da `morph-review`
+> (persona `evaluator`, contexto fresco) sempre lê as 4 rubricas completas — a régua
+> do juiz de fase não muda. Esta condensada só corta releitura no loop intra-task.
+
+## Verificações mecânicas obrigatórias — auto-reprovação (teto 2)
+
+Se o diff toca endpoint minimal API ou fetch cross-camada, independente do resto:
+
+- Serviço injetado na lambda do endpoint sem `AddScoped`/`AddSingleton`/`AddTransient` em `Program.cs`.
+- Chamada server-direct e client-side proxy pro mesmo recurso reusando a mesma constante de prefixo.
+
+## Dimensões e pesos
+
+| Dimensão | Peso |
+|---|---|
+| Arquitetura | 30% |
+| Contratos | 25% |
+| Qualidade de código | 25% |
+| Cobertura de testes | 20% |
+
+## Bandas por dimensão
+
+| Dimensão | 1-3 | 4-6 | 7-8 | 9-10 |
+|---|---|---|---|---|
+| **Arquitetura** | Ignora a arquitetura do spec.md; sem feature folder; deps circulares; ou violação mecânica acima | Pastas corretas, responsabilidades se misturam; deps cross-feature sem justificativa; domain acoplado a infra | Desvios menores justificados; deps cross-feature via abstração; impurezas de infra pontuais | Feature folder rigoroso; zero deps cross-feature diretas; domain isolado; DI onde exige |
+| **Contratos** | Sem tipos ou `any` generalizado; zero validação; sem tratamento de erro; naming arbitrário | `any`/genérico visível; validação parcial; mix exceptions/Result; naming inconsistente | Tipos bem definidos, `any` raro e justificado; validação na maioria; erro consistente | Zero `any`; validação em todos endpoints; Result pattern/discriminated union; naming consistente |
+| **Qualidade** | Nomes arbitrários; god objects; duplicação massiva; fora do padrão do stack | Nomes genéricos (`data`,`temp`); funções >30 linhas; duplicação perceptível | Nomes claros, raras exceções; bem dimensionado; duplicação mínima | Nomes comunicam intenção; funções ≤20-25 linhas, 1 responsabilidade; zero duplicação/dead code |
+| **Testes** | Sem testes ou sem asserts reais; zero edge case; nomes genéricos | Happy path OK, edge cases parciais; erros só óbvios; testes interdependentes | Happy path completo; maioria dos edge cases; erros nos fluxos principais | Toda pós-condição do `usecase` tem teste; A1/A2 cobertos; edge+erro cobertos; isolados |
+
+> Task com `usecase: UC-nn`: pós-condição sem teste **impede a faixa 9-10** em Testes, mesmo com o resto da suíte completo (herdado de `test-coverage.md`).
+
+## Score composto
+
+```
+score = (arquitetura × 0.30) + (contratos × 0.25) + (qualidade × 0.25) + (testes × 0.20)
+```
+
+Arredonde para uma casa decimal. ≥9 aprova em silêncio; <9 alimenta o loop de correção do `morph-apply`.
+
+## Quando abrir a completa em vez desta
+
+Dúvida de banda, violação mecânica suspeita, ou escopo de fase (Gate 3) — abra
+`framework/evals/rubrics/{dimension}.md`. Esta condensada é o atalho do caso comum.

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);