@polymorphism-tech/morph-spec 8.19.0 → 8.21.0

package/framework/hooks/shared/telemetry-logger.js

@@ -16,12 +16,22 @@
  * - Windows-safe paths via path.join
  */
 
-import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'fs';
+import {
+  appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync,
+} from 'fs';
 import { join, dirname } from 'path';
 
 const LOGS_DIR = '.morph/logs';
 export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
 
+// SessionStart (worktree-context.js) rotates events.jsonl once it crosses
+// this size, alongside the pre-existing activity.jsonl rotation — same
+// call site, same "between sessions" checkpoint. events.jsonl has no natural
+// per-turn cap (prompts/commands are truncated at the write site, but the
+// LINE COUNT itself grows unbounded across a long-lived project), so without
+// this it grows forever the way activity.jsonl used to before R1.2.
+export const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024; // 5 MB
+
 function getEventsPath(projectPath) {
   return join(projectPath || process.cwd(), EVENTS_FILE);
 }
@@ -73,3 +83,56 @@ export function readTelemetryEvents(projectPath) {
     return [];
   }
 }
+
+/**
+ * Archive the current events.jsonl to `.morph/logs/sessions/`, mirroring
+ * activity-logger.js's `archiveSession()` — same directory, same rename-not-
+ * rewrite mechanics (O(1) even at multi-MB sizes). Named with an `events-`
+ * prefix (activity-logger's archives carry no prefix) so the two streams
+ * never collide inside the shared `sessions/` directory and stay
+ * distinguishable at a glance.
+ *
+ * Fail-silent — called only from `rotateEventsLogIfLarge` below, which has
+ * already confirmed the file exists.
+ *
+ * @param {string} [projectPath]
+ */
+function archiveEvents(projectPath) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return;
+
+    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
+    mkdirSync(sessionsDir, { recursive: true });
+
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const archivePath = join(sessionsDir, `events-${stamp}.jsonl`);
+    renameSync(eventsPath, archivePath);
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Rotate events.jsonl when it crosses `thresholdBytes`. Called from
+ * worktree-context.js on SessionStart, right next to the existing
+ * `rotateActivityLogIfLarge()` call — the only reliable "between sessions"
+ * checkpoint the harness gets. `thresholdBytes` is injectable so a test can
+ * force rotation without writing multiple megabytes.
+ *
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @param {number} [thresholdBytes] - Rotate once the log is at least this large
+ * @returns {boolean} true if a rotation was performed
+ */
+export function rotateEventsLogIfLarge(projectPath, thresholdBytes = ROTATE_THRESHOLD_BYTES) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return false;
+    const { size } = statSync(eventsPath);
+    if (size < thresholdBytes) return false;
+    archiveEvents(projectPath);
+    return true;
+  } catch {
+    return false;
+  }
+}

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/schemas/tasks.schema.json

@@ -39,7 +39,7 @@
           "standards": {
             "type": "array",
             "items": { "type": "string", "minLength": 1 },
-            "description": "Standards pinned by morph-plan for this task, as paths relative to the framework root (e.g. \"standards/backend/dotnet/vsa-handler-patterns.md\"). Optional. Part of the plan contract: frozen after Gate 2."
+            "description": "Standards pinned by morph-plan for this task, as PATHS relative to the framework root (e.g. \"standards/backend/dotnet/vsa-handler-patterns.md\"). Optional. Part of the plan contract: frozen after Gate 2. NOT the same vocabulary as agents.json's top-level `standards` field, which lists IDs (e.g. \"backend-dotnet-vsa-handler-patterns\", no slashes/extension) — same field name, different shape; do not treat one as the other."
           }
         },
         "additionalProperties": false

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.21.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.21.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.21.0"
 ---
 
 # morph-apply
@@ -208,21 +208,12 @@ Quando `getPendingTasks(data).length === 0`:
 - Invocar `Skill(morph-review)` para gerar `.morph/features/{feature}/4-review/review-report.md`.
 - A skill morph-review chama `morph-eval` em escopo de feature inteira.
 
-### 5. Gate 3 (trust-aware)
+### 5. Gate 3
 
-Rode `morph-spec gate-check {feature} review [--json]` — lê `trust`, decide via `shouldPauseGate` e persiste `gateDecisions.review` 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.
-
-**`evalScore` sem override é uma PROXY** (média das `taskScores`, não o score composto real). Passe o composto do `review-report.md` (avaliador independente) e qualquer violação que ele tenha encontrado via `--signals` — as únicas chaves que este comando aceita sobrescrever:
-```
-morph-spec gate-check {feature} review --signals '{"evalScore":9.2,"standardsViolations":[]}'
-```
-
-Risco que nenhuma dessas chaves representa (julgamento do avaliador que não vira `standardsViolations`): 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 bateu com a decisão persistida.
-
-- Pause: `AskUserQuestion` com options `["aprovado, fechar feature", "preciso ajustar", "rollback"]`.
-- Auto: exibir summary do review-report, aprovar via `morph-spec approve {feature} review --mode auto`, e prosseguir.
+Apresentado e persistido por `morph-review` §8 (invocada no passo 4 acima) — gate-check, template
+fixo nomeando a feature, aprovação registrada pós-resposta. Ao retomar o controle dela, **NÃO
+re-apresente o gate**: siga direto para o encerramento (§6) conforme a decisão já persistida em
+`gateDecisions.review`.
 
 ### 6. Pós Gate 3 — encerramento
 

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.21.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
@@ -147,6 +147,6 @@ options:
 
 ## Referências
 - `.morph/framework/MORPH.md` — seções 1 (Papéis), 2 (Fases), 5 (Gates), Trust Mode
-- `.morph/framework/standards/STANDARDS.json` — para referência de standards relevantes à stack
+- `morph-spec standards --find "<query>"` — para referência de standards relevantes à stack (ver `morph-standards`)
 - `framework/skills/core/morph-stack-scan/SKILL.md` — invocada na Parte 0 (varredura), antes de qualquer pergunta
 - `.morph/framework/MORPH.md` §5 — regras de pausa do Gate 1 (trust mode)

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.21.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.21.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.21.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.21.0"
 ---
 
 # morph-plan
@@ -84,10 +84,10 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
 4. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
    - Stack exata do projeto (leia de `.morph/config/config.json` → `project.stack` ou do CLAUDE.md).
-   - Standards obrigatórios: liste os IDs relevantes de `.morph/framework/standards/STANDARDS.json`.
+   - Standards obrigatórios: descubra-os com `morph-spec standards --find "<domínio/tecnologia>"` (top 3 `id · path · digest` — o digest decide) por domínio tocado; liste os IDs escolhidos.
    - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico `IRepository<T>`/`IUnitOfWork`, SQL cru sem justificativa) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
    - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
-   - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
+   - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via `morph-spec standards --find "<tema>" --category ai-agents`. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - Checklist de done com critérios verificáveis por tarefa.
 
 5. Produza `tasks.json` em `.morph/features/{feature}/2-plan/` seguindo o schema em `.morph/framework/schemas/tasks.schema.json`.
@@ -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.
@@ -197,7 +199,7 @@ Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de
 ## Referências
 
 - `.morph/framework/MORPH.md` — seções 2 (Fases), 3 (Contratos de Output), 5 (Gates), Trust Mode
-- `.morph/framework/standards/STANDARDS.json` — para identificar standards relevantes ao mandate
+- `morph-spec standards --find "<query>"` — para identificar standards relevantes ao mandate (o índice inteiro só como navegação exploratória; ver `morph-standards`)
 - `.morph/framework/agents.json` — personas por domínio; lido UMA VEZ no passo 5a para carimbar `agent`/`standards` por task
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
 - `.morph/specs/usecases/` — acervo permanente de use cases do projeto (leia antes de numerar; em `bug`, é onde mora o UC a corrigir)

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.21.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.21.0"
 ---
 
 # morph-review
@@ -98,7 +98,8 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
 7. **NÃO finalize o trace manualmente.** O hook `trace-autogen` gera e finaliza `.morph/traces/YYYY-MM-DD-{feature}-implement.json` automaticamente (incl. `phase_summary` e `completed_at`) no último write de `tasks.json` — quando a última task sai de `pending`/`in_progress`. Se o trace parecer desatualizado, a causa é um `morph-spec score` faltante ou um recap sem o bloco da task — corrija a fonte, não o trace.
 
-8. Apresente o Gate 3 segundo trust mode.
+8. Apresente o Gate 3 segundo trust mode — **única apresentação do gate**: `morph-apply` §5 aponta
+   para cá em vez de duplicar; ao devolver o controle a ela, o gate já está decidido.
 
    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.
 
@@ -109,7 +110,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
    Julgamento do revisor que nenhuma dessas chaves representa: use `gate-decision` direto em vez de `gate-check`.
 
-   **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.
+   **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 bateu com a decisão persistida.
 
    **Se `pause === true`**, use `AskUserQuestion`:
 

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.21.0"
 ---
 
 # morph-stack-scan

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

@@ -1,17 +1,18 @@
 ---
 name: morph-standards
-description: Localiza e carrega um standard específico do STANDARDS.json sob demanda
+description: Localiza um standard específico via busca server-side (morph-spec standards --find) e carrega só o necessário
 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.21.0"
 ---
 
 # morph-standards
 
 ## Objetivo
-Encontrar o standard certo para a situação atual e carregar apenas esse arquivo no contexto.
-Nunca carregue todos os standards — o custo de token não compensa.
+Encontrar o standard certo para a situação atual e carregar apenas o necessário no contexto.
+Nunca abra o `STANDARDS.json` inteiro (65 KB) — a busca server-side já devolve o suficiente
+para aplicar o standard na maioria dos casos.
 
 ## Quando invocar
 Quando durante a implementação surgir uma dúvida de padrão arquitetural, de contrato, de qualidade
@@ -19,21 +20,33 @@ ou de teste — e o mandate.md não for suficiente para resolver.
 
 ## O que fazer
 
-1. Abra `framework/standards/STANDARDS.json`.
+1. Rode a busca server-side — é O caminho, não uma opção entre várias:
+   ```
+   morph-spec standards --find "<domínio/tecnologia da task>" [--category <cat>] [--tags <a,b>] [--json]
+   ```
+   Devolve o **top 3** como `id · path · digest` — o `digest` é o texto completo do standard;
+   na maioria dos casos ele já basta para aplicar o padrão, sem abrir o `.md`.
 
-2. Filtre por `category` primeiro (valores típicos: "architecture", "contracts", "testing", "frontend", "backend").
+2. Se dois resultados parecerem relevantes e houver conflito, adote o mais específico ao stack
+   do projeto. Registre o conflito no `decisions.md` da feature.
 
-3. Dentro da categoria, filtre por `tags` que correspondam ao stack do projeto
-   (ex: "dotnet", "nextjs", "blazor", "typescript").
+3. Abra o arquivo `.md` do standard (campo `path`) só quando o `digest` não bastar para resolver
+   a dúvida — ex.: precisa de um exemplo de código completo ou de uma seção que o resumo não cobre.
 
-4. Se dois standards parecerem relevantes e houver conflito, adote o mais específico ao stack.
-   Registre o conflito no `decisions.md` da feature.
+4. Aplique o standard na tarefa atual.
 
-5. Leia o arquivo `.md` do standard selecionado — o path está no campo `path` do JSON.
+5. Registre no `recap.md`: qual standard foi consultado (via `--find`, ou navegação — item abaixo)
+   e como foi aplicado.
 
-6. Aplique o standard na tarefa atual.
+## Fallback — navegação exploratória
 
-7. Registre no `recap.md`: qual standard foi consultado e como foi aplicado.
+`--find` exige uma query. Quando a necessidade é genuinamente exploratória (ex.: "o que existe
+pra categoria X?", sem um termo de busca claro), nesta ordem:
+
+1. `morph-spec standards` sem `--find` — lista categorias + contagem, custo mínimo, o suficiente
+   pra decidir qual `--category` usar num `--find` em seguida.
+2. Só se isso não bastar, abra `framework/standards/STANDARDS.json` inteiro — último recurso,
+   nunca o primeiro passo.
 
 ## Quando não há standard adequado
 Registre no `decisions.md` que nenhum standard cobre o caso.
@@ -41,10 +54,11 @@ Descreva o critério adotado e sinalize para revisão futura.
 Não invente um standard — padrões não documentados são dívida técnica.
 
 ## Output esperado
-- Standard identificado e lido no contexto
+- Standard identificado (via `--find`/digest, ou `.md` completo quando necessário) no contexto
 - Critério de implementação claro para a tarefa atual
 - Entrada no recap.md registrando o standard consultado
 
 ## Referências
-- `framework/standards/STANDARDS.json` — índice completo com id, name, path, category, tags
+- `morph-spec standards --find "<query>" [--category] [--tags] [--json]` — busca server-side, top 3 `id · path · digest`
+- `framework/standards/STANDARDS.json` — índice completo; abrir só como fallback exploratório (ver acima)
 - `framework/MORPH.md` — seção 4 (Como consultar 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.21.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.
+
+   **Persona universal** (`ui-designer.stack = ["*"]` em `agents.json`, mesmo mecanismo de `evaluator`/`scout`): UI/UX importa sempre que há superfície de UI, então o subagent está registrado em **todo** projeto — .NET/Blazor incluído, não só Next.js. **Fallback** (caso raro: instalação anterior a essa mudança, `.claude/agents/morph-ui-designer.md` ainda não regenerado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório — resolvido rodando `morph-spec setup-infra --reinstall`.
+
+   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.
+
+   **Hook state-sync reconhece este gate, como os demais.** Igual a Gate 1/2/3, o hook `state-sync.js` (`gateFromQuestion`) reconhece o texto "Gate uiux" — uma resposta "aprovado" ao template acima grava sozinha `approvalGates.uiux = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo, atribuído pelo nome da feature que a pergunta cita (MORPH.md §5). Sem nome na pergunta, ou fora de `AskUserQuestion` (headless/CI): aprove 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.21.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",