@polymorphism-tech/morph-spec 8.19.0 → 8.20.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.20.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.20.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.19.0",
+  "version": "8.20.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.20.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.20.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/docs/CLI.md

@@ -6,7 +6,7 @@
 
 ## 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.

package/framework/phases.json

@@ -33,7 +33,7 @@
       "pausePoints": [
         { "id": "uiux", "label": "Approve UI/UX" }
       ],
-      "skill": null
+      "skill": "morph-uiux"
     },
     "plan": {
       "id": "plan",

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-apply

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

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-brainstorming
@@ -88,7 +88,7 @@ options:
 
 1. Produza `proposal.md` em `.morph/features/{feature}/0-proposal/` com:
    - **Problema:** o que está sendo resolvido e para quem (máx. 2 parágrafos)
-   - **Escopo:** o que está incluído e o que está explicitamente excluído
+   - **Escopo:** o que está incluído e o que está explicitamente excluído — registre se a mudança cria ou altera superfície de UI (componente, página, tela, estilo, fluxo de navegação): é o fato que decide o roteamento para o ramo uiux na `morph-proposal` (critério objetivo em `MORPH.md` §2.1)
    - **Usuários e fluxos críticos:** quem usa e qual é o caminho principal
    - **Stack:** confirme o stack padrão ou documente desvios aprovados
    - **Riscos e dependências:** o que pode dar errado, o que esta feature depende

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

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-implement

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-plan
@@ -132,6 +132,8 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    - `agent`: o `id` da persona (chave do objeto `agents`, sem prefixo `morph-`) cujo `domains` cobre o `group`/domínio da task — o mesmo casamento que `morph-implement` §3 e `morph-apply` §3b fariam manualmente a cada dispatch; aqui você faz uma vez, no plano.
    - `standards`: o array `standards` dessa persona, mais qualquer standard adicional que a task especificamente exija (some, não substitua).
 
+   **Task que cria ou altera superfície de UI** (componente, página, estilo, fluxo de navegação) carimba `agent: "ui-designer"` — inclusive numa feature que não tomou o ramo uiux (MORPH.md §2.1): o critério de agente é por domínio da task, não por fase percorrida.
+
    Uma task cujo domínio não bate com nenhuma persona registrada (ex.: task pura de config/docs) fica sem `agent` — `morph-implement` cai no fallback de Read de `agents.json` nesse caso.
 
    **O `doneCriteria` carrega a pós-condição LITERAL.** Este é o elo que amarra a cadeia inteira: a pós-condição escrita em linguagem de negócio chega **sem tradução** ao critério que o `morph-spec verify` e o `morph-eval` cobram. Copie o texto da pós-condição, prefixado pelo seu rótulo (`"P2 — Cada veterinário traz..."`). Reescrever com outras palavras aqui é exatamente o ponto em que o requisito se perde hoje.

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-proposal
@@ -98,6 +98,13 @@ morph-spec approve {feature} proposal --mode auto
 morph-spec advance {feature}
 ```
 
+### 3a. Roteamento uiux (após o Gate 1)
+
+Critério objetivo em `MORPH.md` §2.1: a mudança cria ou altera superfície de UI (componente, página, tela, estilo, fluxo de navegação)?
+
+- **Sim** → em vez do `advance {feature}` do passo 3, rode `morph-spec advance {feature} --design` (cria `1-design/`) e invoque `Skill(morph-uiux)`. Ela conduz a fase de design e, com o Gate uiux aprovado, devolve o controle aqui — siga para o passo 4.
+- **Não** → nenhuma ação extra; o `advance {feature}` do passo 3 já criou `2-plan/` direto.
+
 ### 4. Verificar retomada antes de morph-plan
 
 - Se `.morph/features/{feature}/2-plan/spec.md` já existe: pular para passo 6 (Gate 2).
@@ -129,6 +136,7 @@ Mesma mecânica do passo 3: a decisão já foi tomada e persistida pela `morph-p
 ## Output esperado
 
 - `.morph/features/{feature}/0-proposal/proposal.md`
+- `.morph/features/{feature}/1-design/` (se o ramo uiux — passo 3a — foi tomado)
 - `.morph/features/{feature}/2-plan/spec.md`
 - `.morph/features/{feature}/2-plan/mandate.md`
 - `.morph/features/{feature}/2-plan/tasks.json`
@@ -139,6 +147,7 @@ Mesma mecânica do passo 3: a decisão já foi tomada e persistida pela `morph-p
 - `.morph/framework/MORPH.md` — charter NLH completo
 - `.morph/framework/MORPH.md` §2.1 — roteamento por tipo de trabalho (Passo 0)
 - `framework/skills/core/morph-brainstorming/SKILL.md`
+- `framework/skills/core/morph-uiux/SKILL.md` — invocada no passo 3a quando a feature toma o ramo uiux
 - `framework/skills/core/morph-plan/SKILL.md`
 - `framework/skills/core/morph-hotfix/SKILL.md` — pipeline invocado pelo branch `hotfix` do Passo 0
 - `.morph/framework/MORPH.md` §5 — regras de pausa de gate (trust mode)

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-stack-scan

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

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.19.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-standards

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

@@ -0,0 +1,135 @@
+---
+name: morph-uiux
+description: Conduz a fase opcional de UI/UX — design system, mockups, componentes e fluxos — entre o Gate 1 e o plan, despachando a persona ui-designer para o trabalho visual.
+version: core
+when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
+user-invokable: true
+cliVersion: "8.20.0"
+---
+
+# morph-uiux
+
+## Objetivo
+
+Produzir os artefatos de `1-design/` com qualidade de produção — boas práticas de UI/UX, usabilidade, consistência com o padrão visual do projeto, tecnologia de ponta do stack instalado — e apresentar o Gate uiux antes de entregar a feature ao `morph-plan`.
+
+## Quando invocar
+
+Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfície de UI (componente, página, tela, estilo, fluxo de navegação) — critério objetivo em `MORPH.md` §2.1. Normalmente invocada pela `morph-proposal` logo após o Gate 1, via `morph-spec advance {feature} --design`. Sem essa condição a feature segue direto para `morph-plan` e esta skill nunca é chamada.
+
+## O que fazer
+
+1. **Garanta os insumos em contexto** — use a tool Read se não estiver:
+   - `.morph/features/{feature}/0-proposal/proposal.md` — problema, escopo, usuários e fluxos.
+   - `.morph/context/design-system.md` (se existir) — o design system **vivo** do projeto: toda decisão de token/componente parte dele, nunca do zero. Ausente → greenfield de design; use `.morph/framework/templates/context/design-system.md` como forma de partida.
+   - `.morph/config/config.json` → `project.stack` — decide a tecnologia de ponta a aplicar (`nextjs` → Tailwind + shadcn + Framer Motion; outro stack → o equivalente idiomático dele). Nunca hardcode Next.js quando o stack detectado é outro.
+   - `.morph/features/{feature}/0-proposal/stack-scan.md` (se existir) — desvios de stack já detectados.
+
+2. **Princípios de qualidade** (decisão do produto — não são opcionais):
+   - **Usabilidade e acessibilidade:** WCAG AA, todos os estados de componente interativo cobertos (default/hover/focus/disabled/loading/error) — não só o caminho feliz.
+   - **Consistência:** reusa tokens/componentes existentes de `.morph/context/design-system.md` antes de criar novos; um token novo precisa de justificativa (o existente não cobre o caso).
+   - **Tecnologia de ponta condicionada ao stack real** (passo 1) — nunca a suposição de que o projeto é Next.js.
+   - **Sistemas, não telas isoladas** — mesmo critério da persona `ui-designer`: componentes reutilizáveis antes de composições de uso único.
+
+3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem `Read/Write/Edit/Glob/Grep` + MCPs `stitch`/`gemini-image`/`playwright`/`context7`, mas **não tem Bash** — não peça build, testes nem `morph-spec` a ele; isso é do orquestrador.
+
+   **Fallback — caminho normal fora de stack Next.js** (`ui-designer.stack = ["nextjs"]` em `agents.json`, então em qualquer outro stack o subagent não está registrado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório. Isto não é uma exceção rara — é o caminho normal para projetos não-Next.js.
+
+   Template do prompt (contrato do relatório em forma curta — copia o padrão de `morph-implement` §4, sem a cláusula de build/isolamento, que não se aplica a um agente sem Bash):
+   ```
+   Produzir os artefatos de UI/UX de [feature] em `.morph/features/{feature}/1-design/`.
+
+   Contexto: [problema/escopo do proposal.md] + design system atual
+   (`.morph/context/design-system.md`, tokens/componentes a reusar) + stack: [stack real do config.json]
+
+   Produza, NESTA ORDEM — design-system.md primeiro, os demais só como aplicável ao escopo:
+   1. `design-system.md` — tokens (cor, tipografia, espaço, motion) consistentes com o projeto
+   2. `mockups.md` — descrição estruturada de cada tela nova/alterada (+ imagem via MCP
+      gemini-image/stitch quando disponível; fallback: descrição textual detalhada)
+   3. `components.md` — inventário de componentes novos/reusados, com props e os estados do
+      princípio 2 acima
+   4. `flows.md` — fluxos de navegação/interação entre as telas
+
+   Done quando: os artefatos aplicáveis existem e cada um cita os tokens/componentes do
+   design-system.md em vez de reinventar valores soltos.
+
+   Contrato do relatório final:
+   1. GRAVE um relatório por artefato produzido em
+      `1-design/reports/[artefato]-report.md` (ex.: `1-design/reports/design-system-report.md`)
+      ANTES de encerrar — é o retorno autoritativo, não a sua mensagem final (cortesia
+      best-effort, pode não chegar inteira). NÃO chame SendMessage.
+   2. Você não tem Bash — não rode `morph-spec`, build nem testes; a aprovação do Gate uiux
+      e qualquer comando CLI são do orquestrador.
+   3. NÃO toque em tasks.json, feature.json, state.json nem no board de sessão.
+
+   Cada relatório contém: (1) o que foi feito em 2-3 frases, (2) o artefato produzido,
+   (3) decisões de design e por quê (token reusado vs. novo, padrão de acessibilidade
+   aplicado), (4) auto-score 0-10 com justificativa em uma linha. Relatório ausente, oco,
+   ou sem os 4 itens, é falha de protocolo.
+   ```
+
+   Após o retorno: **leia primeiro** `1-design/reports/*-report.md` — valor de retorno autoritativo, a mensagem de texto é atalho best-effort quando chega inteira. `design-system.md` é o único output obrigatório (`phases.json → uiux.requiredOutputs`); sem ele em disco, `morph-spec advance` recusa avançar — confirme que existe antes de rodar `advance` no passo 6.
+
+4. **Atualize o design system vivo do projeto** — se a Parte 3 introduziu tokens/componentes novos, aplique o mesmo protocolo do `morph-brainstorming` (Parte 0): atualize `.morph/context/design-system.md` com a adição e uma entrada de changelog (data, motivo). `1-design/design-system.md` é o artefato **da feature** (o que ela usa/introduz); `.morph/context/design-system.md` é o acervo vivo do **projeto** — não confunda os dois.
+
+5. **Os artefatos alimentam o `morph-plan` seguinte.** Use cases e tasks de UI referenciam `1-design/mockups.md`/`components.md` **por path** (ex.: doneCriteria citando a seção do mockup) — não redigite conteúdo visual em `spec.md`.
+
+6. Apresente o Gate uiux.
+
+   Rode `morph-spec gate-check {feature} uiux [--json]` — mesma mecânica de `morph-plan`/`morph-review`: lê `trust`, decide via `shouldPauseGate` e persiste `gateDecisions.uiux` com timestamp server-side. Divergência de design-system detectada aqui (fonte do projeto vs. o que a feature precisa) é uma das poucas chaves que `--signals` aceita sobrescrever:
+   ```
+   morph-spec gate-check {feature} uiux --signals '{"designSystemDivergence":true}'
+   ```
+
+   **Se `pause === true`**, use `AskUserQuestion`:
+   ```
+   question: "Gate uiux — Design de {feature} aprovado?{ reason ? ' Sinal: ' + reason : '' }"
+   header: "Gate uiux"
+   options:
+     - { label: "aprovado, prosseguir", description: "Aceitar design-system/mockups/components/flows e avançar para o plano" }
+     - { label: "preciso ajustar", description: "Apontar mudanças no design antes de prosseguir" }
+     - { label: "cancelar feature", description: "Abortar" }
+   ```
+
+   Aguardar resposta. Se "preciso ajustar", aplicar e reapresentar.
+
+   **Divergência do hook state-sync — só neste gate:** ao contrário de Gate 1/2/3, o hook `state-sync.js` (`gateFromQuestion`) não reconhece o texto "Gate uiux" — uma resposta "aprovado" aqui **não** grava o gate sozinha. Depois do "aprovado", grave explicitamente:
+   ```
+   morph-spec approve {feature} uiux --approver <quem respondeu>
+   # ou, para já aprovar e criar 2-plan/ num passo só:
+   morph-spec advance {feature} --approver <quem respondeu>
+   ```
+   (o `--approver` importa aqui: sem ele, num terminal não-interativo `advance`/`approve` resolvem `approvedBy: "auto"` — que MORPH.md §5 proíbe registrar quando quem aprovou foi um humano.)
+
+   **Se `pause === false`** (auto-aprovação, sem `AskUserQuestion`), exibir summary curto e já aprovar via CLI:
+   ```
+   ## Gate uiux (auto-aprovado)
+
+   **Design system:** {tokens novos, se houver} | **Mockups:** {N telas}
+   **Components:** {N novos / N reusados} | **Flows:** {N fluxos}
+   ```
+   ```
+   morph-spec advance {feature}
+   ```
+
+   Os 4 outputs de `1-design/` (`protected: true, approvalGate: 'uiux'`) travam na aprovação — retrabalho de design depois do gate passa pelo gate de novo (revogar, ajustar, reapresentar), nunca por Edit direto no arquivo travado.
+
+   **Próximo passo (não é desta skill):** com o Gate uiux aprovado e `2-plan/` criado, devolva o controle a quem invocou (`morph-proposal`, passo 4/5) — ela invoca `Skill(morph-plan)`. Não invoque `morph-plan` diretamente daqui.
+
+## Output esperado
+
+- `.morph/features/{feature}/1-design/design-system.md` — obrigatório
+- `.morph/features/{feature}/1-design/mockups.md`, `components.md`, `flows.md` — conforme o escopo exigir
+- `.morph/features/{feature}/1-design/reports/*-report.md` — relatório(s) bruto(s) do `morph-ui-designer` despachado no passo 3
+- `.morph/context/design-system.md` atualizado (se tokens/componentes novos entraram) com entrada de changelog
+- Gate uiux registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
+
+## Referências
+
+- `.morph/framework/MORPH.md` §2.1 — critério objetivo de entrada no ramo uiux
+- `.morph/framework/MORPH.md` §6 — protocolo de dispatch e contrato do relatório final
+- `.morph/framework/MORPH.md` §5 — regras de pausa de gate (trust mode)
+- `.morph/framework/agents.json` — persona `ui-designer` (tools, MCPs, standards)
+- `.morph/framework/templates/context/design-system.md` — forma de partida quando o projeto não tem design system vivo
+- `framework/skills/core/morph-brainstorming/SKILL.md` — protocolo de reconciliação/changelog do design-system vivo (Parte 0), reaplicado no passo 4
+- `framework/skills/core/morph-plan/SKILL.md` — consome os artefatos desta fase por path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.19.0",
+  "version": "8.20.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",