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

package/bin/morph-spec.js

@@ -428,7 +428,8 @@ program
 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('--by <mode>', 'Group by: task|phase (default: feature-wide summary; with --all-trees, applies to the combined aggregate)')
+  .option('--all-trees', 'Aggregate .morph/logs/events.jsonl across every git worktree that has one, not just the current tree — per-tree breakdown + combined total')
   .option('--json', 'Output the aggregate as JSON')
   .action((feature, options) => costCommand(feature, options));
 

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.19.0",
+  "version": "8.21.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.19.0 by Polymorphism Tech*
+*morph-spec v8.21.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.19.0 by Polymorphism Tech*
+*morph-spec v8.21.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -79,6 +79,7 @@ Prefixo de todo comando: `morph-spec`. Flags/exemplos: `.morph/framework/CLI.md`
 |-------|-------------|
 | `morph-brainstorming` | Entender negócio, escanear stack, produzir proposal.md |
 | `morph-stack-scan` | Detectar desvios de stack em projeto brownfield |
+| `morph-uiux` | Ramo opcional uiux — design system, mockups, componentes, fluxos |
 | `morph-plan` | Destilar use cases e produzir spec.md + mandate.md + tasks.json |
 | `morph-implement` | Executar uma tarefa com auto-advance entre tasks |
 | `morph-eval` | Aplicar rubricas e produzir score 0-10 |
@@ -88,7 +89,7 @@ Prefixo de todo comando: `morph-spec`. Flags/exemplos: `.morph/framework/CLI.md`
 
 ## Roteamento por tipo de trabalho
 
-`workType` (`create --type <tipo>` ou classificado de `--request`) dimensiona o pipeline: `feature` completo, `bug` enxuto, `chore` fast-track (Gates 1/2 por política), `hotfix` scout→fix→gate humano→ship. Canônico: `MORPH.md` §2.1/§5.
+`workType` (`create --type <tipo>` ou classificado de `--request`) dimensiona o pipeline: `feature` completo (+ ramo uiux quando há superfície de UI), `bug` enxuto, `chore` fast-track (Gates 1/2 por política), `hotfix` scout→fix→gate humano→ship. Canônico: `MORPH.md` §2.1/§5.
 
 Features independentes rodam em paralelo, uma por git worktree (`create --worktree`/`worktree setup`), bloco de portas próprio + handoff.md. Fechamento: `finish <f> --pr|--merge`; agregado: `fleet`. Canônico: `MORPH.md` §2.2.
 
@@ -104,15 +105,6 @@ Drift entre `agents.json` e os `.md` gerados é detectado por `morph-spec doctor
 
 ## Regra de precedência de skills
 
-Em projetos morph-spec, prefira as skills `morph-*` sobre as equivalentes `superpowers:*`:
-
-| Em vez de | Use |
-|-----------|-----|
-| `superpowers:brainstorming` | `morph-brainstorming` |
-| `superpowers:writing-plans` | `morph-plan` |
-| `superpowers:executing-plans` | `morph-apply` |
-| `superpowers:test-driven-development` | seguir `mandate.md` (TDD está embutido) |
-
-As skills `morph-*` aplicam Gates e leem/produzem outputs nos paths corretos de `.morph/`. As `superpowers:*` são genéricas e não conhecem o contexto morph-spec.
+Prefira `morph-*` a `superpowers:*` equivalentes (`brainstorming`→`morph-brainstorming`, `writing-plans`→`morph-plan`, `executing-plans`→`morph-apply`, `test-driven-development`→seguir `mandate.md`, TDD embutido): `morph-*` aplica Gates e paths corretos de `.morph/`; `superpowers:*` é genérico, sem esse contexto.
 
 *MORPH-SPEC v5 by Polymorphism Tech*

package/framework/MORPH.md

@@ -12,19 +12,19 @@
 
 Entre gates, você opera com autonomia total. O dev valida. Você executa.
 
-| Situação                                                              | O que você faz                                                                |
-|-----------------------------------------------------------------------|-------------------------------------------------------------------------------|
-| Gate 1 / 2 / 3 aprovado                                               | Avançar para próxima fase imediatamente                                       |
-| Tarefa completada na fase implement                                   | Iniciar a próxima task do tasks.json sem aguardar instrução                   |
-| Ambiguidade de escopo coberta pelo mandate                            | Resolver conservadoramente e registrar em decisions.md                        |
-| Ambiguidade bloqueante (requisito ausente ou contraditório)           | UMA pergunta via AskUserQuestion                                              |
-| Sub-agent retornou relatório (qualquer auto-score)                    | Auto-score é triagem, não aprovação: a task só avança com morph-eval ≥ 9      |
-| Sub-agent com auto-score < 7                                          | Re-despachar com feedback específico (ou corrigir inline) antes do morph-eval |
-| Build/typecheck quebra                                                | Corrigir antes de marcar tarefa como done                                     |
-| Task implementada (código escrito)                                    | `morph-spec verify <feature> <task>` ANTES do juiz: vermelho = feedback ao loop sem gastar o morph-eval; verde → morph-eval avalia o que o código não pega |
-| Score morph-eval ≥ 9                                                  | Silêncio (aprovação implícita), próxima tarefa                                |
-| Score morph-eval < 9 numa task                                        | Loop de correção autônomo: re-implementar com feedback priorizado, até 3 tentativas, sem pausa humana |
-| Score morph-eval < 9 após 3 tentativas                                | Escalar ao usuário (aceitar/continuar/pular) — único ponto de pausa do loop  |
+| Situação | O que você faz |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Gate 1 / 2 / 3 aprovado | Avançar para próxima fase imediatamente |
+| Tarefa completada na fase implement | Iniciar a próxima task do tasks.json sem aguardar instrução |
+| Ambiguidade de escopo coberta pelo mandate | Resolver conservadoramente e registrar em decisions.md |
+| Ambiguidade bloqueante (requisito ausente ou contraditório) | UMA pergunta via AskUserQuestion |
+| Sub-agent retornou relatório (qualquer auto-score) | Auto-score é triagem, não aprovação: a task só avança com morph-eval ≥ 9 |
+| Sub-agent com auto-score < 7 | Re-despachar com feedback específico (ou corrigir inline) antes do morph-eval |
+| Build/typecheck quebra | Corrigir antes de marcar tarefa como done |
+| Task implementada (código escrito) | `morph-spec verify <feature> <task>` ANTES do juiz: vermelho = feedback ao loop sem gastar o morph-eval; verde → morph-eval avalia o que o código não pega |
+| Score morph-eval ≥ 9 | Silêncio (aprovação implícita), próxima tarefa |
+| Score morph-eval < 9 numa task | Loop de correção autônomo: re-implementar com feedback priorizado, até 3 tentativas, sem pausa humana |
+| Score morph-eval < 9 após 3 tentativas | Escalar ao usuário (aceitar/continuar/pular) — único ponto de pausa do loop |
 
 **Regra de ouro:** dúvida que não bloqueia → resolver e registrar; dúvida que bloqueia → uma pergunta, máximo. Vale **entre gates** (plan/implement/review) — **não** vale na abertura da feature: a fase proposal pode rodar em **modo entrevista** (escolhido na pergunta de abertura, `morph-brainstorming` Parte 2), onde perguntar até fechar o entendimento é o comportamento desejado.
 
@@ -36,16 +36,16 @@ Entre gates, você opera com autonomia total. O dev valida. Você executa.
 
 O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos que haja ambiguidade real.
 
-| Camada     | Stack                                                                                            |
-|------------|--------------------------------------------------------------------------------------------------|
-| Backend    | .NET 10 + VSA (feature-folder: handler + validator + endpoint + errors + tests)                  |
-| ORM/DB     | EF Core + Neon (Postgres)                                                                         |
-| IDs        | `Guid.CreateVersion7()` (nunca `Guid.NewGuid()`)                                                 |
-| Classes    | `sealed` por padrão                                                                              |
-| Erros      | Result pattern com `result.Match()` (nunca exceptions como fluxo)                                |
-| IA         | Microsoft Agent Framework (MAF) — quando houver agentes                                          |
-| Frontend   | Next.js App Router + Tailwind + Framer Motion + Shadcn                                           |
-| Jobs async | Hangfire — apenas quando há razão real                                                           |
+| Camada | Stack |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| Backend | .NET 10 + VSA (feature-folder: handler + validator + endpoint + errors + tests) |
+| ORM/DB | EF Core + Neon (Postgres) |
+| IDs | `Guid.CreateVersion7()` (nunca `Guid.NewGuid()`) |
+| Classes | `sealed` por padrão |
+| Erros | Result pattern com `result.Match()` (nunca exceptions como fluxo) |
+| IA | Microsoft Agent Framework (MAF) — quando houver agentes |
+| Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
+| Jobs async | Hangfire — apenas quando há razão real |
 
 Padrões proibidos automaticamente injetados no mandate:
 - `Guid.NewGuid()` → `Guid.CreateVersion7()`
@@ -77,16 +77,16 @@ Os papéis não são exclusivos — numa sessão longa você transita entre eles
 
 O fluxo padrão de uma feature tem quatro fases, cada uma com pasta dedicada em `.morph/features/{feature}/`. Estado autoritativo e commitado: `.morph/features/{feature}/feature.json` (status, approvalGates, outputs, tasks, gateDecisions, taskScores, archivedAt); `.morph/state.json` na raiz é só índice fino gitignored derivado dele; identidade do projeto em `.morph/config/config.json` (commitado).
 
-| Fase        | Pasta          | Gate                  | O que termina a fase                            |
-|-------------|----------------|-----------------------|-------------------------------------------------|
-| proposal    | `0-proposal/`  | Gate 1 (trust-aware)  | `proposal.md` aprovado e commitado              |
-| plan        | `2-plan/`      | Gate 2 (trust-aware)  | `spec.md`, `mandate.md`, `tasks.json` aprovados |
-| implement   | `3-implement/` | Nenhum                | Todas as tasks do tasks.json com status `done`  |
-| review      | `4-review/`    | Gate 3 (trust-aware)  | `review-report.md` aprovado e commitado         |
+| Fase | Pasta | Gate | O que termina a fase |
+| ------------- | ---------------- | ----------------------- | ------------------------------------------------- |
+| proposal | `0-proposal/` | Gate 1 (trust-aware) | `proposal.md` aprovado e commitado |
+| plan | `2-plan/` | Gate 2 (trust-aware) | `spec.md`, `mandate.md`, `tasks.json` aprovados |
+| implement | `3-implement/` | Nenhum | Todas as tasks do tasks.json com status `done` |
+| review | `4-review/` | Gate 3 (trust-aware) | `review-report.md` aprovado e commitado |
 
 A fase `proposal` tem dois **modos de descoberta**, escolhidos pelo usuário na abertura (só `workType: feature`/`bug` — `chore`/`hotfix` nascem em `implement`): **entrevista** (uma pergunta por vez até a árvore de decisões abertas zerar; Gate 1 pausa sempre) e **automático** (até 4 perguntas em lote; Gate 1 trust-aware). Nos dois modos a varredura do ambiente roda **antes** de qualquer pergunta — fato que `morph-stack-scan` ou o acervo de use cases responde não vira pergunta. Detalhes em `morph-brainstorming`.
 
-A fase `1-design/` (design system, mockups, flows) é opcional — só para features com UI nova, requisitada explicitamente pelo usuário.
+A fase `1-design/` é opcional — critério objetivo de entrada em §2.1.
 
 Não avance de fase sem o gate correspondente ter sido confirmado.
 
@@ -95,12 +95,14 @@ Não avance de fase sem o gate correspondente ter sido confirmado.
 Nem todo trabalho merece o pipeline completo. Cada feature nasce com **identidade** (`name` = slug + `description` obrigatória) e um **workType** (`morph-spec create <f> --description "<o quê/porquê>" --type <tipo>`, ou classificado de `--request "<pedido>"`, que também semeia a descrição) que dimensiona o pipeline:
 
 | Tipo | Pipeline | Gates |
-|------|----------|-------|
+| ------ | ---------- | ------- |
 | `feature` | proposal → [uiux] → plan → implement → review (completo) | 1, 2, 3 |
 | `bug` | repro+diagnóstico enxuto (proposal lean) → plan enxuto → implement → review | 1, 2, 3 |
 | `chore` | fast-track: direto para implement (Gates 1/2 carimbados por política no nascimento) → review leve | só 3 |
 | `hotfix` | scout (diagnóstico read-only) → fix cirúrgico → **aprovação humana obrigatória** → test loop → ship | 3 (humano sempre) |
 
+**Ramo uiux (critério objetivo):** feature/bug que cria ou altera superfície de UI (componente, página, tela, estilo, fluxo de navegação) toma o ramo `1-design/` via `morph-spec advance {feature} --design`; sem superfície de UI, direto para plan. Skill: `morph-uiux`. Avaliado por `morph-proposal`/`morph-brainstorming` no fecho do Gate 1 — não redecida em nenhum outro ponto do pipeline.
+
 **Como classificar (router):** sinais determinísticos primeiro — `morph-spec create --request "<texto>"` roda o detector por keywords (hotfix: "produção caiu/urgente/incident/p0"; bug: "bug/corrigir/exception/regressão"; chore: "typo/rename/bump/config/docs/cleanup"). As keywords casam como **palavra inteira** ("group0" não é `p0`, "prefix" não é `fix`, "debug" não é `bug`) — casar demais pularia gates num pedido inócuo; por isso plural e flexão são listados explicitamente ("bugs", "incidentes", "configs"). Confiança `high` → usa o tipo. Empate (`tie`) ou nenhum sinal (`none`) → o comando sai com código 2 e os candidatos; **você decide como roteador** e re-roda com `--type`. Só vale uma `AskUserQuestion` quando o pedido é genuinamente indeterminado.
 
 **Como o skip funciona:** `chore`/`hotfix` têm os gates `proposal`/`plan` carimbados no nascimento com `approvedBy: "policy:{tipo}"`. Como `derivePhase` é gate-aware, o trabalho já nasce em `implement` — sem tocar `phases.json`. Artefatos reutilizam os nomes canônicos (hotfix escreve brief curto em `proposal.md`; ambos escrevem `2-plan/tasks.json` mínimo de 1-3 tasks para ligar trace/score/dag).
@@ -212,7 +214,7 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), auto-pas
 **Sinais de risco que forçam pausa em auto** (`gate-check` aplica esta tabela via `shouldPauseGate` — fonte única; sinal que só a sessão conhece escala via `gate-decision` manual):
 
 | Sinal | Threshold | Quando aplica |
-|-------|-----------|---------------|
+| ------- | ----------- | --------------- |
 | `designSystemDivergence` | true | Brainstorming detecta fontes conflitantes (spec antigo vs bundle local) |
 | `standardsViolations` | array.length > 0 | Mandate ou implementation viola padrões proibidos |
 | `evalScore` | < 9 | score composto da feature (via morph-review) abaixo do mínimo |
@@ -220,7 +222,7 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), auto-pas
 | `workType` | === 'hotfix' | Gate 3 pausa SEMPRE (detalhe abaixo, "Gates por tipo de trabalho") |
 
 | Gate | Sinais | Skill responsável |
-|------|--------|--------------------|
+| ------ | -------- | -------------------- |
 | 1 — Proposta | `designSystemDivergence`, `standardsViolations` (improvável) | `morph-brainstorming` |
 | 2 — Plano | Gate 1 + `taskCount`, `standardsViolations` em mandate | `morph-plan` |
 | 3 — Review | `evalScore` composite, `standardsViolations` em implementation | `morph-review` |
@@ -287,7 +289,7 @@ morph-spec report-check <feature> [task] --json
 ```
 
 | veredito | o que significa | ação |
-|---|---|---|
+| --- | --- | --- |
 | `ok` | relatório presente e com os 4 itens | siga o fluxo |
 | `report-incomplete` | relatório existe, faltam itens (ele lista quais) | complete a partir da mensagem de retorno, carimbe **DEGRADADO** |
 | `work-landed-report-missing` | sem relatório, mas os `outputs` da task estão no disco | **não re-despache** — grave você mesmo o relatório canônico a partir da mensagem de retorno, carimbado **DEGRADADO** |
@@ -330,27 +332,23 @@ Não invoque uma skill fora do momento indicado.
 
 Path de cada skill: `framework/skills/core/{nome}/SKILL.md`.
 
-| Skill                 | Quando invocar                                                          |
-|-----------------------|---------------------------------------------------------------------------|
-| **morph-proposal**    | **Orquestrador**: brainstorming → Gate 1 → plan → Gate 2 (entry point) |
-| **morph-apply**       | **Orquestrador**: DAG-adaptive implement loop → review → Gate 3        |
-| morph-brainstorming   | Invocada pela morph-proposal — entendimento de negócio + stack-scan    |
-| morph-stack-scan      | Detecta stack atual; curto-circuita em greenfield                       |
-| morph-plan            | Invocada pela morph-proposal — produz spec/mandate/tasks.json           |
-| morph-implement       | Invocada pela morph-apply — executa cada task                           |
-| morph-eval            | Após concluir uma task ou fase                                          |
-| morph-review          | Invocada pela morph-apply — produz review-report + Gate 3               |
-| morph-hotfix          | **Orquestrador**: ADW cirúrgico de hotfix (scout → fix → gate humano → ship) |
-| morph-standards       | Quando precisar localizar ou aplicar um standard específico             |
-
-**Entry points** para o usuário:
-- `/morph-proposal {feature}` → invoca `Skill(morph-proposal)`, que orquestra brainstorming + plan
-- `/morph-apply {feature}` → invoca `Skill(morph-apply)`, que orquestra implement + review
-- `/morph-hotfix {feature}` → invoca `Skill(morph-hotfix)`, o pipeline cirúrgico de correção em produção
-
-Slash commands são atalhos: o agente pode chamar `Skill(morph-proposal)` diretamente quando o usuário pede "use /morph-proposal".
-
-Cada skill contém instruções passo a passo. Leia, siga, não desvie sem justificativa no recap.md. Apenas `framework/skills/core/` é instalado. Nenhuma skill deve ser invocada proativamente por um hook ou script — skills são instrumentos do modelo, você decide quando a situação pede o rigor que a skill fornece.
+| Skill | Quando invocar |
+| ----------------------- | --------------------------------------------------------------------------- |
+| **morph-proposal** | **Orquestrador**: brainstorming → Gate 1 → plan → Gate 2 (entry point) |
+| **morph-apply** | **Orquestrador**: DAG-adaptive implement loop → review → Gate 3 |
+| morph-brainstorming | Invocada pela morph-proposal — entendimento de negócio + stack-scan |
+| morph-stack-scan | Detecta stack atual; curto-circuita em greenfield |
+| morph-uiux | Ramo opcional uiux (§2.1) — design system, mockups, componentes, fluxos |
+| morph-plan | Invocada pela morph-proposal — produz spec/mandate/tasks.json |
+| morph-implement | Invocada pela morph-apply — executa cada task |
+| morph-eval | Após concluir uma task ou fase |
+| morph-review | Invocada pela morph-apply — produz review-report + Gate 3 |
+| morph-hotfix | **Orquestrador**: ADW cirúrgico de hotfix (scout → fix → gate humano → ship) |
+| morph-standards | Quando precisar localizar ou aplicar um standard específico |
+
+Slash commands (`/morph-proposal`, `/morph-apply`, `/morph-hotfix` — linhas acima) são atalhos que invocam a `Skill()` correspondente; o agente pode chamá-la direto quando o usuário pede "use /morph-proposal".
+
+Cada skill contém instruções passo a passo — leia, siga, não desvie sem justificativa no recap.md. Só `framework/skills/core/` é instalado. Nenhuma skill é invocada proativamente por hook ou script — você decide quando a situação pede o rigor dela.
 
 ---
 

package/framework/agents.json

@@ -102,7 +102,7 @@
         "design", "ui", "ux", "design system", "tokens", "wcag",
         "accessibility", "mockup", "flow", "shadcn", "tailwind"
       ],
-      "stack": ["nextjs"],
+      "stack": ["*"],
       "standards": [
         "frontend-design-system-naming",
         "frontend-design-system-animations",

package/framework/docs/CLI.md

@@ -6,10 +6,10 @@
 
 ## Gates e estado
 
-- **`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 approve <feature> <gate> --mode auto`** — aprova um gate (`proposal`/`uiux`/`plan`/`review`) em `trust: auto`. **`uiux`** é o único gate cujo `AskUserQuestion` o hook `state-sync.js` não reconhece por texto (só casa "Gate 1/2/3") — aprove-o sempre explicitamente por este comando ou por `advance`, nunca contando com o hook. **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 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-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate.
+- **`morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate. Um stamp `pass` mas **stale** (sha diferente do HEAD atual — código mudou depois do último verify) força pausa **só no ship** (`review`); em `plan`/`uiux`/`proposal` a staleness é computada e reportada em `signals`, mas não pausa nada — é regra de ship, não de gate genérico. Stamp **ausente** nunca pausa por isso (features legadas sem stamp).
 - **`morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`** — o **escape manual**: registra uma decisão já tomada pela sessão (ex.: `discoveryMode: "interview"`, sinal que `shouldPauseGate` nem representa). Mesmo write path do `gate-check` — 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.
 
 ## Features
@@ -38,4 +38,4 @@
 ## Observabilidade
 
 - **`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.
+- **`morph-spec cost [feature] [--by task|phase] [--all-trees] [--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 eram observáveis por hook até o evento `SessionUsage` — quando presente no stream, `inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheCreationTokens` são somados e exibidos à parte como "tokens reais", nunca misturados com a proxy de bytes). `--all-trees` agrega `.morph/logs/events.jsonl` de **toda árvore git** que tiver um (não só a corrente) — reusa a mesma enumeração de worktree do `doctor --worktrees`/`fleet`; mostra um resumo por árvore + o total combinado (`--by` aplica ao agregado combinado). Use antes/depois de mudar skill ou fluxo para medir o efeito.

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

@@ -102,8 +102,29 @@ export async function run(payload) {
       // 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;
+        // uiux is OPTIONAL — proposal approval alone is enough to enter
+        // 2-plan/ for a feature that never took the design branch (no
+        // 1-design/ dir), exactly as before this check. But once a feature
+        // HAS opted into uiux (1-design/ exists), that gate is not
+        // decorative: 2-plan/ must wait for it too, or a feature can skip
+        // straight from an approved proposal into planning with its design
+        // gate silently left pending.
+        const tookDesignBranch = targetDir === '2-plan'
+          && existsSync(resolveTargetPath(`.morph/features/${featureName}/1-design`, root));
+
+        if (!tookDesignBranch || isGateApproved(featureName, 'uiux', root)) {
+          logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+          return null;
+        }
+
+        logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
+        return blockResult(
+          `MORPH-SPEC: Writing to '2-plan/' is not allowed yet.\n` +
+          `This feature entered the uiux branch (1-design/ exists) and the 'uiux' gate is still pending.\n\n` +
+          `Approve the design gate first, then re-enter plan:\n` +
+          `  morph-spec approve ${featureName} uiux\n` +
+          `  morph-spec advance ${featureName}`
+        );
       }
 
       const phaseLabel = phase.toUpperCase();

package/framework/hooks/claude-code/core/state-sync.js

@@ -94,6 +94,11 @@ function isApprovalAnswer(answer) {
 
 function gateFromQuestion(question) {
   if (typeof question !== 'string') return null;
+  // Checked BEFORE the generic patterns below: the pinned uiux template is
+  // "Gate uiux — Design de {feature} aprovado?" (morph-uiux/SKILL.md) — it
+  // must never fall through to 'plan' via a stray "plan"/"plano" substring in
+  // the feature name. `/gate\s+uiux/i` alone is unambiguous either way.
+  if (/gate\s+uiux/i.test(question)) return 'uiux';
   const lower = question.toLowerCase();
   if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
   if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -41,6 +41,32 @@ function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
+// events.jsonl grows forever across a project's lifetime (R2 rotation caps
+// the FILE, not any single line) — a multi-KB sub-agent prompt or a long
+// Bash command written verbatim on every dispatch/call is the dominant per-
+// line cost. Capped AT THE WRITE SITE (not in the shared logger, so every
+// OTHER event type stays exactly as-is) to `MAX_FIELD_CHARS`, with the
+// ORIGINAL length preserved in a sibling `<field>Chars` key — `morph-spec
+// cost` sums prompt chars for its dispatch-cost view, and must prefer that
+// field over `prompt.length` once it's present (a truncated string's own
+// length would silently undercount every dispatch over the cap). This shape
+// is a CONTRACT with the telemetry reader — do not rename either half.
+const MAX_FIELD_CHARS = 2000;
+const TRUNCATE_SUFFIX = '…[truncado]';
+
+/**
+ * Cap a free-text field (prompt/command) at MAX_FIELD_CHARS, always
+ * reporting the field's true original length alongside it.
+ *
+ * @param {string} value
+ * @returns {{ value: string, chars: number }}
+ */
+function capField(value) {
+  const str = typeof value === 'string' ? value : '';
+  if (str.length <= MAX_FIELD_CHARS) return { value: str, chars: str.length };
+  return { value: str.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
+}
+
 /**
  * Classify a Read target into the telemetry `kind` taxonomy — a contract with
  * the observability side (src/lib/telemetry/telemetry-reader.js), so these
@@ -144,7 +170,8 @@ export async function run(payload) {
 
     // UserPromptSubmit carries the user's prompt and no tool_name.
     if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
-      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: payload.prompt || '' };
+      const userPrompt = capField(payload.prompt || '');
+      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: userPrompt.value, promptChars: userPrompt.chars };
     } else {
       const tool = payload.tool_name;
       if (!tool) return null;
@@ -156,7 +183,9 @@ export async function run(payload) {
       } else if (tool === 'Agent' || tool === 'Task') {
         event.persona = input.subagent_type || '';
         if (input.description) event.desc = input.description;
-        event.prompt = input.prompt || '';
+        const dispatchPrompt = capField(input.prompt || '');
+        event.prompt = dispatchPrompt.value;
+        event.promptChars = dispatchPrompt.chars;
       } else if (tool === 'Read') {
         event.target = targetFilePath || normalize(input.file_path || input.path);
         event.kind = classifyReadKind(event.target);
@@ -169,7 +198,9 @@ export async function run(payload) {
           // omit bytes
         }
       } else if (tool === 'Bash') {
-        event.command = input.command || '';
+        const bashCommand = capField(input.command || '');
+        event.command = bashCommand.value;
+        event.commandChars = bashCommand.chars;
       } else if (tool === 'Write' || tool === 'Edit') {
         event.target = normalize(input.file_path || input.path);
       } else {

package/framework/hooks/claude-code/core/validate-completion.js

@@ -21,7 +21,7 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { runBuildCheck } from '../../shared/build-check.js';
@@ -30,6 +30,7 @@ import {
 } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
+import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 
 /**
  * Audit recap.md against tasks.json + standard-citation rule.
@@ -121,6 +122,80 @@ function auditRecapAndTasks(featurePath) {
   return warnings;
 }
 
+// Safety valve for a pathological outlier transcript — NOT needed for the
+// normal case: a real 45 MB / ~16k-line transcript (inspected directly while
+// building this) parses+sums in ~350ms locally, well inside a Stop hook's
+// budget. Above this, skip rather than risk an unbounded read.
+const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024; // 50 MB
+
+/**
+ * Sum real token usage from a Claude Code session transcript (JSONL, the
+ * `transcript_path` the Stop payload carries).
+ *
+ * Each assistant TURN is written to the transcript as MULTIPLE JSONL lines —
+ * one per content block (thinking/text/tool_use) — every one of them
+ * repeating the exact SAME turn-level `message.usage` object under the same
+ * `message.id`. Verified against a real transcript: 5982 assistant lines but
+ * only 3315 unique message ids, with byte-identical usage across duplicates
+ * of the same id — summing every line naively double/triple-counts (measured
+ * ~2x on output_tokens on that file). This is why a per-line sum is wrong and
+ * a dedup-by-id sum is required; there is no running/cumulative total field
+ * to lean on instead — each turn's `usage` is that turn's own cost.
+ *
+ * Tolerant to shape: any missing usage field reads as 0. A corrupt/truncated
+ * line is skipped, not fatal — same discipline as telemetry-logger's reader.
+ *
+ * @param {string} [transcriptPath]
+ * @returns {{inputTokens:number,outputTokens:number,cacheReadTokens:number,cacheCreationTokens:number}|null}
+ *   null when there is nothing to report (no path, missing/oversized/
+ *   unreadable file, or zero assistant messages carrying usage).
+ */
+function computeSessionUsage(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+  try {
+    if (!existsSync(transcriptPath)) return null;
+    if (statSync(transcriptPath).size > MAX_TRANSCRIPT_BYTES) return null;
+
+    const raw = readFileSync(transcriptPath, 'utf-8');
+    let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreationTokens = 0;
+    const seenMessageIds = new Set();
+    let sawAny = false;
+
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let entry;
+      try {
+        entry = JSON.parse(trimmed);
+      } catch {
+        continue; // one corrupt/truncated line must not lose the whole transcript
+      }
+      if (entry?.type !== 'assistant') continue;
+      const usage = entry?.message?.usage;
+      if (!usage || typeof usage !== 'object') continue;
+
+      // Dedup by message.id (fallback to the line's own uuid when a message
+      // carries none) — first occurrence wins, duplicates carry identical
+      // values so which one wins never matters.
+      const dedupKey = entry?.message?.id || entry?.uuid;
+      if (dedupKey) {
+        if (seenMessageIds.has(dedupKey)) continue;
+        seenMessageIds.add(dedupKey);
+      }
+
+      sawAny = true;
+      inputTokens += Number(usage.input_tokens) || 0;
+      outputTokens += Number(usage.output_tokens) || 0;
+      cacheReadTokens += Number(usage.cache_read_input_tokens) || 0;
+      cacheCreationTokens += Number(usage.cache_creation_input_tokens) || 0;
+    }
+
+    return sawAny ? { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } : null;
+  } catch {
+    return null; // fail-open
+  }
+}
+
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
@@ -128,12 +203,15 @@ const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
 
 /**
- * @param {object} _payload - parsed Stop stdin payload (unused — this hook
- *   reads its own state from disk, not from the tool payload)
+ * @param {object} payload - parsed Stop stdin payload. Most of this hook's
+ *   logic reads its own state from disk rather than the payload, EXCEPT the
+ *   session-usage capture below, which needs `payload.transcript_path` (and
+ *   `payload.session_id` for the throttle key) — the one thing only the
+ *   payload carries.
  * @returns {Promise<object|null>} a hookSpecificOutput advisory (phase
  *   transition / build failure / recap drift), or null (pass/silent).
  */
-export async function run(_payload) {
+export async function run(payload) {
   try {
     // Prevent infinite loop
     if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') return null;
@@ -264,6 +342,40 @@ export async function run(_payload) {
     }
     // ────────────────────────────────────────────────────────────────────────
 
+    // ── Session usage (real tokens, from the transcript) ──────────────────────
+    // Silent side effect — never contributes to `warnings`/additionalContext,
+    // same as telemetry-log.js's capture. Throttled: only re-emitted when the
+    // computed totals actually changed since the last SessionUsage recorded
+    // for this session_id, so an unchanged transcript across consecutive
+    // Stops (no new assistant turn) does not re-append an identical event.
+    try {
+      const usage = computeSessionUsage(payload?.transcript_path);
+      if (usage) {
+        const usagePath = join(memDir, 'session-usage.json');
+        let stored = {};
+        try {
+          if (existsSync(usagePath)) stored = JSON.parse(readFileSync(usagePath, 'utf-8'));
+        } catch { /* corrupt file — start fresh */ }
+
+        const sessionKey = payload?.session_id || 'default';
+        const last = stored[sessionKey];
+        const unchanged = last
+          && last.inputTokens === usage.inputTokens
+          && last.outputTokens === usage.outputTokens
+          && last.cacheReadTokens === usage.cacheReadTokens
+          && last.cacheCreationTokens === usage.cacheCreationTokens;
+
+        if (!unchanged) {
+          appendTelemetryEvent({ event: 'SessionUsage', ...usage }, cwd);
+          stored[sessionKey] = usage;
+          try { writeFileSync(usagePath, JSON.stringify(stored, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+        }
+      }
+    } catch {
+      // Fail-open — usage capture must never block Stop
+    }
+    // ────────────────────────────────────────────────────────────────────────
+
     if (warnings.length === 0) return null;
 
     const message = [

package/framework/hooks/claude-code/core/worktree-context.js

@@ -27,7 +27,10 @@
  * Also the real call site for activity-log rotation (R1.2 of the performance
  * plan): SessionStart is the only reliable "between sessions" checkpoint the
  * harness gets, so this is where `.morph/logs/activity.jsonl` gets archived
- * to `.morph/logs/sessions/` once it crosses the size threshold.
+ * to `.morph/logs/sessions/` once it crosses the size threshold. The same
+ * checkpoint now also rotates `.morph/logs/events.jsonl` (telemetry-logger.js)
+ * once IT crosses its own threshold — events.jsonl grew unbounded even after
+ * R1.2, since that rotation only ever covered activity.jsonl.
  *
  * Fail-open: any error, or nothing to report, → pass() silently. This hook
  * never blocks a session from starting.
@@ -46,6 +49,7 @@ import {
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
 import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
+import { rotateEventsLogIfLarge } from '../../shared/telemetry-logger.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -223,10 +227,11 @@ export async function run(payload) {
       return null;
     }
 
-    // Rotate the activity log before anything else touches it this session.
-    // Best-effort, never fatal to session start — rotateActivityLogIfLarge()
-    // is itself fail-open (returns false on any error).
+    // Rotate the activity + events logs before anything else touches them
+    // this session. Best-effort, never fatal to session start — both rotate*
+    // helpers are themselves fail-open (return false on any error).
     try { rotateActivityLogIfLarge(dir); } catch { /* non-blocking */ }
+    try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);