@polymorphism-tech/morph-spec 8.18.0 → 8.20.0

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.18.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.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-hotfix
@@ -81,10 +81,10 @@ Use `--skip-tests`/`--skip-build` quando fizer sentido para velocidade (ex.: ite
 
 ### 7. Gate 3 — SEMPRE humano
 
-O hotfix tem `forcedPauseGates: ['review']` (`src/core/work-types.js`) — o Gate 3 pausa **sempre**, mesmo em `trust: auto`. Persista a decisão antes de apresentar:
+O hotfix tem `forcedPauseGates: ['review']` (`src/core/work-types.js`) — o Gate 3 pausa **sempre**, mesmo em `trust: auto`. `gate-check` já sabe disso: lê `workType` do disco e `shouldPauseGate` força a pausa antes de checar qualquer outro sinal — rode direto, sem `--signals`:
 
 ```
-morph-spec gate-decision {feature} review --pause true --reason "hotfix: aprovação humana obrigatória" --signals '{"workType":"hotfix","evalScore":X}'
+morph-spec gate-check {feature} review [--json]
 ```
 
 Escreva `4-review/review-report.md` curto: diff do fix + evidência real de teste (saída do `verify` do passo 6). Depois, **`AskUserQuestion` SEMPRE**:
@@ -137,4 +137,4 @@ morph-spec approve {feature} review --approver "<nome de quem aprovou>"
 - `src/core/work-types.js` — `scaffold`/`skippedGates`/`forcedPauseGates` do tipo `hotfix`
 - `morph-spec create {feature} --type hotfix` — nascimento com política de gates
 - `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores
-- `morph-spec gate-decision {feature} review --pause true [--reason ...] [--signals ...]` — persiste a decisão de pausa antes do Gate 3
+- `morph-spec gate-check {feature} review [--json]` — persiste a decisão de pausa (forçada por `workType: hotfix`) antes do Gate 3

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.18.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.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-plan
@@ -45,25 +45,22 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    2. Sistema retorna os veterinários ordenados por sobrenome
    3. Sistema exibe, para cada um, nome e especialidades
 
-   ## Fluxos alternativos
-   - **A1** — Nenhum veterinário cadastrado → sistema exibe estado vazio
-   - **A2** — Veterinário sem especialidade → sistema exibe "sem especialidade"
-
    ## Pós-condições
    - **P1** — A resposta contém todos os veterinários não arquivados
    - **P2** — Cada veterinário traz suas especialidades em lista, nunca string concatenada
    - **P3** — A ordenação por sobrenome é estável para nomes repetidos
 
-   ## Delta de domínio
-   - `Vet.archivedAt` (novo, nullable) — habilita P1
-   - Nenhuma relação nova
+   ## Fluxos alternativos (opcional)
+   - **A1** — Nenhum veterinário cadastrado → sistema exibe estado vazio
    ```
 
    **A regra que sustenta a camada inteira: pós-condição precisa ser observável em teste.** "O sistema fica consistente" não passa. "A resposta contém todos os veterinários não arquivados" passa. Antes de escrever cada pós-condição, pergunte: *que asserção eu escreveria para verificar isto?* Se não há resposta, a pós-condição está mal formulada — reescreva ou descarte. Sem esse filtro a camada vira prosa e não chega ao `doneCriteria`.
 
    **Identificador sequencial no projeto, não na feature.** Antes de numerar, leia o acervo `.morph/specs/usecases/` (se existir) mais os use cases das features ativas em `.morph/features/*/2-plan/usecases/`; tome o maior `UC-{nn}` e some um. Numerar por feature garante colisão no momento da promoção.
 
-   **Seções:** `Pré-condições` (o que já é verdade antes), `Cenário principal` (o caminho feliz, numerado), `Fluxos alternativos` (**A1**, **A2**… — cada alternativa aproxima uma user story; edge case de *comportamento* mora aqui, edge case *técnico* fica no `spec.md`), `Pós-condições` (**P1**, **P2**… — o que passa a ser verdade, cada uma testável) e `Delta de domínio` (**só o que muda**: campo novo, relação nova, invariante nova — o modelo completo continua sendo o código EF Core mais as migrations; se a feature não altera o domínio, escreva "nenhum").
+   **Seções obrigatórias:** `Pré-condições` (o que já é verdade antes), `Cenário principal` (o caminho feliz, numerado, **curto** — não é o lugar para exaustão de casos) e `Pós-condições` (**P1**, **P2**… — o que passa a ser verdade, cada uma testável; é a seção que viaja **literal** ao `doneCriteria`, ver abaixo).
+
+   **Seções opcionais** — inclua só quando o comportamento não-trivial exigir, não por padrão: `Fluxos alternativos` (**A1**, **A2**… — um desvio do caminho feliz que precisa de pós-condição própria; edge case de *comportamento* mora aqui, edge case *técnico* fica no `spec.md`) e `Delta de domínio` (**só quando a feature muda o modelo**: campo novo, relação nova, invariante nova — sem delta, omita a seção em vez de escrever "nenhum"). Nenhuma das duas é consumida por `dag`/`finish` — existem para o leitor humano quando o caso pede, não para preencher o template.
 
    **Quando é obrigatório** (ver MORPH.md §2.1 para o roteamento por tipo):
 
@@ -135,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.
@@ -151,21 +150,16 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
    Você pode embutir o diagrama do DAG do plano via `morph-spec dag {feature} --mermaid` (flowchart Mermaid) para visualização no gate.
 
-   Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular os sinais de risco em linguagem natural — sem scripts:
-
-   - `taskCount` = número de tasks do tasks.json.
-   - `designSystemDivergence` = herdado do brainstorming.
-   - `standardsViolations` = violações detectadas no mandate.
-
-   **Decisão de pausa** (regras da tabela do MORPH.md §5): `trust: manual` → pausa sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; `taskCount > 20` → pausa; caso contrário → auto-passa (`pause: false`).
-
-   **Persista a decisão ANTES de apresentar ou auto-aprovar — via CLI, nunca editando feature.json à mão** (o Edit manual colide com o hook state-sync, que reescreve o arquivo entre o seu Read e o Edit — erro "file modified since read"):
+   Rode `morph-spec gate-check {feature} plan [--json]` — lê `trust` de `.morph/config/config.json`, conta `taskCount` do `tasks.json` (disco), decide via `shouldPauseGate` e persiste `gateDecisions.plan` com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`), imprimindo `pause`/`reason`/`signals`. É o default — não recompute a tabela do MORPH.md §5 em linguagem natural.
 
+   `gate-check` **não herda** `designSystemDivergence` do Gate 1 automaticamente — é recomputado a cada chamada. Se a divergência do Gate 1 segue sem resolução, ou o mandate introduziu uma violação de standard, repasse via `--signals` (as únicas chaves que este comando aceita sobrescrever):
    ```
-   morph-spec gate-decision {feature} plan --pause false --reason "nenhum sinal de risco" --signals '{"taskCount":12,"standardsViolations":[]}'
+   morph-spec gate-check {feature} plan --signals '{"designSystemDivergence":true,"standardsViolations":["<id>"]}'
    ```
 
-   O comando grava `gateDecisions.plan = { pause, reason, signals, trust, decidedAt }` no `feature.json` autoritativo com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`). Isso deixa o raciocínio de trust auditável no disco: o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com esta decisão e avisa em caso de divergência. Sem este registro o guard não tem como verificar — não pule.
+   Risco que nenhuma dessas chaves representa (julgamento desta sessão, não fato de disco): use `gate-decision` direto em vez de `gate-check`.
+
+   **Nunca edite `feature.json` à mão** (colide com o hook state-sync — erro "file modified since read"). Os caminhos acima gravam no mesmo lugar; o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com a decisão persistida.
 
    **Se `pause === true`**, use `AskUserQuestion`:
 

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.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-proposal
@@ -65,13 +65,7 @@ No **modo entrevista** o Gate 1 pausa sempre — a confirmação do entendimento
 
 ### 3. Gate 1 (trust-aware)
 
-Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular sinais de risco:
-
-- `discoveryMode` — `"interview"` ou `"auto"`, decidido na pergunta de abertura da morph-brainstorming.
-- `designSystemDivergence` — detectado pela morph-brainstorming.
-- `standardsViolations` — violações de mandate listadas na proposal (não deveria, mas verifica).
-
-**Decisão de pausa** (regras da tabela do MORPH.md §5, aplicadas em linguagem natural — sem scripts): `discoveryMode: "interview"` → `pause: true` sempre; `trust: manual` → `pause: true` sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → `pause: false` (auto-passa). Monte `reason` com o sinal que disparou.
+A decisão de pausa já foi tomada e persistida pela `morph-brainstorming` (Parte 4): `morph-spec gate-check {feature} proposal` no caminho comum (`shouldPauseGate`; divergência de design-system detectada entra via `--signals`), ou `gate-decision` manual quando `discoveryMode: "interview"` — o único sinal que `shouldPauseGate` não representa. Leia `gateDecisions.proposal` em `feature.json` (ou o output do comando) para `pause`/`reason`.
 
 **Se `pause === true`**, apresentar via `AskUserQuestion`:
 
@@ -104,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).
@@ -118,13 +119,7 @@ A skill lê `proposal.md` e produz:
 
 ### 6. Gate 2 (trust-aware)
 
-Sinais de risco para Gate 2 incluem **mais** do que Gate 1:
-
-- Todos os do Gate 1.
-- `taskCount` — count(tasks.json.tasks). Threshold: 20.
-- `standardsViolations` detectadas no mandate (improvável, mas verificar).
-
-Lógica idêntica ao passo 3 (`shouldPauseGate` + AskUserQuestion ou auto-aprovação).
+Mesma mecânica do passo 3: a decisão já foi tomada e persistida pela `morph-plan` (passo 6) — `morph-spec gate-check {feature} plan` no caminho comum (`shouldPauseGate` sobre `taskCount` do disco; `designSystemDivergence`/`standardsViolations` via `--signals` quando aplicável — não são herdados automaticamente entre gates), ou `gate-decision` manual para risco que nenhuma dessas chaves representa. Leia `gateDecisions.plan` para `pause`/`reason` e apresente com o mesmo template (AskUserQuestion ou auto-aprovação) do passo 3.
 
 ### 7. Conclusão
 
@@ -141,6 +136,7 @@ Lógica idêntica ao passo 3 (`shouldPauseGate` + AskUserQuestion ou auto-aprova
 ## 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`
@@ -151,6 +147,7 @@ Lógica idêntica ao passo 3 (`shouldPauseGate` + AskUserQuestion ou auto-aprova
 - `.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.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-review
@@ -68,9 +68,12 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          um turno inútil ao orquestrador.
          Seu relatório (no arquivo, e na mensagem final quando ela chega)
          deve conter: score 0-10 por dimensão, score composto (arch×0.30 +
-         contracts×0.25 + quality×0.25 + tests×0.20), e feedback priorizado
-         (bloqueantes primeiro) para qualquer dimensão < 9. Relatório
-         ausente, oco, ou sem esses itens, é falha de protocolo.
+         contracts×0.25 + quality×0.25 + tests×0.20) gravado TAMBÉM como a
+         linha literal `**Composite-Score:** {n.n}` (machine-readable — o
+         `morph-spec gate-check` lê o score real daí em vez do proxy de
+         taskScores), e feedback priorizado (bloqueantes primeiro) para
+         qualquer dimensão < 9. Relatório ausente, oco, ou sem esses itens,
+         é falha de protocolo.
      ```
    - **Fallback (tipo não registrado):** se `morph-evaluator` não estiver na sua lista de subagent types, despache `general-purpose` colando o campo `persona` do agente `evaluator` (Read em `.morph/framework/agents.json`) no topo do prompt — e **registre o fallback no review-report** (seção de método).
    - **Leia primeiro** `.morph/features/{feature}/4-review/evaluator-report.md` — é o valor de retorno autoritativo, não a mensagem de texto do dispatch (que é cortesia, útil só quando chega inteira). Os scores por dimensão e o composto do review-report vêm **desse arquivo**, não da sua auto-avaliação. Se o arquivo vier ausente, oco, ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
@@ -97,12 +100,16 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
 8. Apresente o Gate 3 segundo trust mode.
 
-   Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular os sinais de risco em linguagem natural — sem scripts:
+   Rode `morph-spec gate-check {feature} review [--json]` — lê `trust` de `.morph/config/config.json`, decide via `shouldPauseGate` e persiste `gateDecisions.review` com timestamp server-side, imprimindo `pause`/`reason`/`signals`. É o default — não recompute a tabela do MORPH.md §5 em linguagem natural.
 
-   - `evalScore` = score composto retornado pelo **avaliador independente** (passo 4).
-   - `standardsViolations` = ids dos itens bloqueantes de standard encontrados no passo 3.
+   **`evalScore` sem override é uma PROXY** (média das `taskScores`, não o composto real). Passe o composto retornado pelo **avaliador independente** (passo 4) e qualquer item bloqueante encontrado nas **verificações mecânicas sempre-rodar** do passo 3 via `--signals` — as únicas chaves que este comando aceita sobrescrever:
+   ```
+   morph-spec gate-check {feature} review --signals '{"evalScore":9.2,"standardsViolations":[]}'
+   ```
+
+   Julgamento do revisor que nenhuma dessas chaves representa: use `gate-decision` direto em vez de `gate-check`.
 
-   **Decisão de pausa** (mesmas regras da tabela do MORPH.md §5): `trust: manual` → `pause: true` sempre; `standardsViolations` não-vazio → `pause: true`; `evalScore < 9` → `pause: true`; caso contrário → `pause: false` (auto-passa).
+   **Nunca edite `feature.json` à mão** (colide com o hook state-sync). Os caminhos acima gravam no mesmo lugar; o hook `gate-guard.js` confere depois se a ação bateu com a decisão persistida.
 
    **Se `pause === true`**, use `AskUserQuestion`:
 

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

@@ -1,10 +1,10 @@
 ---
 name: morph-stack-scan
-description: Varre o codebase existente, detecta stack atual, compara com o stack padrão e gera migration-plan.md se houver desvios
+description: Varre o codebase existente, detecta stack atual, compara com o stack padrão e registra desvios em stack-scan.md
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-stack-scan
@@ -108,29 +108,25 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    | Runtime | .NET X | .NET 10 | ✓ / ✗ |
    ...
 
-   ## Desvios
+   ## Desvios (ordenados por severidade)
    ### Bloqueantes
-   - {desvio}: {onde foi encontrado} — impacto: {o que quebra se não migrar}
+   - {desvio}: {onde foi encontrado} — impacto: {o que quebra se não migrar} — esforço: {estimativa}
 
    ### Não bloqueantes
-   - {desvio}: {onde foi encontrado} — migração: {como resolver}
+   - {desvio}: {onde foi encontrado} — migração: {como resolver} — esforço: {estimativa}
 
    ## Recomendação
    {Em compliance — prosseguir para morph-brainstorming}
-   {ou: Migração necessária antes de prosseguir — veja migration-plan.md}
+   {ou: Migração necessária antes de prosseguir — ver Desvios acima}
    ```
 
-4. Se houver desvios bloqueantes ou altos, produza `migration-plan.md` em `.morph/features/{feature}/0-proposal/` com:
-   - Lista de desvios ordenados por severidade
-   - Para cada desvio: o que migrar, como migrar, estimativa de esforço, ordem sugerida
-   - Pergunta única via `AskUserQuestion`: "Esta migração deve ser incluída na feature atual ou tratada numa feature separada?"
+4. Se houver desvios bloqueantes ou altos, pergunte via `AskUserQuestion`: "Esta migração deve ser incluída na feature atual ou tratada numa feature separada?" A resposta é decisão humana — registre-a na seção "Compliance de stack" do `proposal.md` (produzido pela `morph-brainstorming`), não num artefato novo: a lista de desvios com impacto/esforço já vive no `stack-scan.md` acima.
 
 5. Se não houver desvios (ou apenas baixos): informe "codebase em compliance com o stack padrão" e prossiga para morph-brainstorming ou morph-plan conforme o contexto.
 
 ## Output esperado
-- `.morph/features/{feature}/0-proposal/stack-scan.md` — resultado da varredura
-- `.morph/features/{feature}/0-proposal/migration-plan.md` — apenas se houver desvios altos/bloqueantes
-- Decisão documentada: incluir migração nesta feature ou separar
+- `.morph/features/{feature}/0-proposal/stack-scan.md` — resultado da varredura, com desvios ordenados por severidade e esforço estimado
+- Decisão documentada: incluir migração nesta feature ou separar (registrada no proposal.md pela morph-brainstorming)
 
 ## Referências
 - `framework/MORPH.md` — seção 4 (Standards), seção 2 (Fases)

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.18.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.18.0",
+  "version": "8.20.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/status.js

@@ -62,7 +62,7 @@ function getPhaseStatus(phaseKey, currentPhase, feature) {
  */
 function checkPhaseOutputs(phaseKey, feature) {
   const phaseOutputMap = {
-    proposal: ['proposal', 'stackScan', 'migrationPlan'],
+    proposal: ['proposal', 'stackScan'],
     uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
     plan: ['spec', 'mandate', 'tasks', 'decisions'],
     implement: ['recap'],
@@ -100,7 +100,7 @@ function formatPhase(phaseKey, currentPhase, feature, options = {}) {
   // Add output files if verbose
   if (options.verbose && status !== 'pending' && status !== 'skipped') {
     const phaseOutputMap = {
-      proposal: ['proposal', 'stackScan', 'migrationPlan'],
+      proposal: ['proposal', 'stackScan'],
       uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
       plan: ['spec', 'mandate', 'tasks', 'decisions'],
       implement: ['recap'],