@polymorphism-tech/morph-spec 8.18.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.18.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.18.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.20.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -36,6 +36,7 @@ import { archiveCommand } from '../src/commands/state/archive.js';
 import { finishCommand } from '../src/commands/state/finish.js';
 import { scoreCommand } from '../src/commands/state/score.js';
 import { gateDecisionCommand } from '../src/commands/state/gate-decision.js';
+import { gateCheckCommand } from '../src/commands/state/gate-check.js';
 import { createCommand } from '../src/commands/state/create.js';
 import { retypeCommand } from '../src/commands/state/retype.js';
 import { handoffCommand } from '../src/commands/state/handoff.js';
@@ -205,6 +206,14 @@ program
   .option('--reason <reason>', 'Reason for revocation')
   .action((feature, gate, options) => unapproveCommand(feature, gate, options));
 
+program
+  .command('gate-check <feature> <gate>')
+  .description('Decide + record a gate\'s trust decision from disk-derived signals (shouldPauseGate) — the deterministic default; see gate-decision for the manual escape hatch')
+  .option('--signals <json>', 'Override ONLY standardsViolations/designSystemDivergence/evalScore (not derivable from disk) — everything else is read from feature.json/tasks.json/git and cannot be overridden here')
+  .option('--trust <mode>', 'Trust mode to decide with (default: config.json → trust, or "auto")')
+  .option('--json', 'Output as JSON')
+  .action((feature, gateArg, options) => gateCheckCommand(feature, gateArg, options));
+
 program
   .command('gate-decision <feature> <gate>')
   .description('Record the trust decision for a gate in feature.json (gateDecisions, server-side timestamp)')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.18.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.18.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.18.0 by Polymorphism Tech*
+*morph-spec v8.20.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -20,7 +20,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - Editar `.morph/specs/usecases/` à mão — só o `finish` escreve lá (lê de `2-plan/usecases/`, carimba `status: implemented`, sobrescreve por ID). Mudar um UC existente (caso `bug`): copie para `2-plan/usecases/` da feature e corrija lá.
 - Listar perguntas em texto simples — sempre `AskUserQuestion` (1-4 perguntas por chamada).
 - Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), ou SQL cru sem justificativa.
-- Editar `taskScores`, `gateDecisions` ou gates de `feature.json` à mão — sempre via `morph-spec score`/`gate-decision`/`approve` (timestamps server-side; Edit manual colide com o hook `state-sync`).
+- Editar `taskScores`, `gateDecisions` ou gates de `feature.json` à mão — sempre via `morph-spec score`/`gate-check`/`approve` (timestamps server-side; Edit manual colide com o hook `state-sync`).
 
 **SEMPRE:**
 - Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
@@ -51,8 +51,9 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 |---------|-----------|
 | `approve <f> <gate> --mode auto` | Aprova gate em `trust:auto`. Gate 3 exige `evaluator-report.md` (ou `--self-assessed`); `hotfix` nunca aceita `--mode auto` — use `--approver` |
 | `advance <f>` | Aprova o gate corrente + já cria a pasta da próxima fase |
-| `score <f> <task> <n> [--dims a,c,q,t]` | Grava `taskScores` server-side — nunca edite à mão |
-| `gate-decision <f> <gate> --pause <bool>` | Grava `gateDecisions` server-side — nunca edite à mão |
+| `score <f> <task> <n> [--dims a,c,q,t]` | Grava `taskScores` server-side (nunca à mão) |
+| `gate-check <f> <gate> [--json]` | Default: decide via sinais do disco (`shouldPauseGate`) |
+| `gate-decision <f> <gate> --pause <bool>` | Escape manual: risco que o disco não vê |
 | `create <f> --description "..." --type <t>` | Nasce a feature + `feature.json`; `--worktree` já isola |
 | `list [--all] [--json]` | Quadro de auditoria: feature × workType × status × gates |
 | `delete <f> [--archive] [--force]` | Remove feature; recusa se gate aprovado sem `--force` |
@@ -70,7 +71,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `telemetry [--feature] [--limit]` | Caminho de execução da sessão a partir de `events.jsonl` |
 | `cost [f] [--by task\|phase]` | Custo (bytes/duração) a partir do mesmo log |
 
-Todo comando é `morph-spec <comando>`. Referência completa (flags, semântica, exemplos): `.morph/framework/CLI.md`.
+Prefixo de todo comando: `morph-spec`. Flags/exemplos: `.morph/framework/CLI.md`.
 
 ## Skills core (em `.claude/skills/`)
 
@@ -78,6 +79,7 @@ Todo comando é `morph-spec <comando>`. Referência completa (flags, semântica,
 |-------|-------------|
 | `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 |
@@ -87,7 +89,7 @@ Todo comando é `morph-spec <comando>`. Referência completa (flags, semântica,
 
 ## 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.
 
@@ -103,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).
@@ -138,7 +140,7 @@ Não invente caminhos alternativos.
 
 ### Plan (`2-plan/`)
 
-- `usecases/UC-{nn}-{slug}.md` — **um arquivo por use case**, o artefato de comportamento da feature. Frontmatter (`id`, `title`, `actor`, `status`, `entities`) mais as seções `Pré-condições`, `Cenário principal`, `Fluxos alternativos` (A1, A2… — cada alternativa aproxima uma user story), `Pós-condições` (P1, P2…) e `Delta de domínio` (**só o que muda** — o domínio completo continua sendo o código EF Core mais as migrations).
+- `usecases/UC-{nn}-{slug}.md` — **um arquivo por use case**, o artefato de comportamento da feature. Frontmatter (`id`, `title`, `actor`, `status`, `entities`) mais as seções obrigatórias `Pré-condições`, `Cenário principal` (curto) e `Pós-condições` (P1, P2…). `Fluxos alternativos` (A1, A2…) e `Delta de domínio` são **opcionais** — só quando o comportamento não-trivial exigir (detalhe: `morph-plan`).
 
   **Pós-condição precisa ser observável em teste** — a regra que sustenta a camada. "O sistema fica consistente" não passa; "a resposta contém todos os veterinários não arquivados" passa. Chega **literal** ao `doneCriteria` da task que a realiza — tradução manual nesse ponto é o que hoje perde o requisito.
 
@@ -209,10 +211,10 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), auto-pas
 - "cancelar feature"   (Gate 3 usa "rollback" em vez de "cancelar")
 ```
 
-**Sinais de risco que forçam pausa em auto** (as skills aplicam estas regras em linguagem natural — a tabela abaixo é a fonte única):
+**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` |
@@ -235,7 +237,7 @@ Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `
 
 **Registre quem aprovou (`approvedBy`):** objeto `{ approved, timestamp, approvedBy }`. `"auto"` — política `trust: auto` sem decisão humana. `"manual"` — humano aprovou explicitamente (via `AskUserQuestion`, ou, sem ela em headless, via texto começando em "aprovado"); em `trust: manual` todo gate é `"manual"` — nunca grave `"auto"` num gate que um humano aprovou. Mantém o audit trail honesto nos contextos headless (CI, `claude -p`) onde mais importa.
 
-**O hook gate-guard.js** confere, sem bloquear, se a ação tomada num gate (pausar vs auto-aprovar) bateu com a decisão de trust via `shouldPauseGate`. A skill **persiste** essa decisão antes de agir — via `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`, gravando `gateDecisions[gate] = { pause, reason, signals, trust, decidedAt }` server-side (shape em `framework/schemas/feature.schema.json`). **Nunca edite `gateDecisions` à mão** — colide com state-sync. Divergência → o guard injeta aviso no contexto; cada conferência registra `coherent`/`divergent` em `.morph/logs/activity.json` — nunca bloqueia.
+**O hook gate-guard.js** confere, sem bloquear, se a ação tomada num gate (pausar vs auto-aprovar) bateu com a decisão persistida. **Default:** `gate-check <feature> <gate> [--signals <json>] [--json]` decide via `shouldPauseGate`; `--signals` sobrescreve só o que o disco não expõe sozinho (`designSystemDivergence`, `standardsViolations`, `evalScore`). **Escape manual** (sinal que `shouldPauseGate` nem representa, ex.: modo de descoberta): `gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`. Ambos gravam `gateDecisions[gate] = { pause, reason, signals, trust, decidedAt }` server-side (shape em `framework/schemas/feature.schema.json`). **Nunca edite `gateDecisions` à mão** — colide com state-sync. Divergência → o guard injeta aviso no contexto; cada conferência registra `coherent`/`divergent` em `.morph/logs/activity.json` — nunca bloqueia.
 
 ---
 
@@ -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/commands/morph-hotfix.md

@@ -21,7 +21,7 @@ Resolve uma queda ou bug crítico de produção com prioridade máxima em veloci
 3. **Hotfix brief:** escreve `0-proposal/proposal.md` curto (sintoma/root cause/blast radius/plano do fix) e `2-plan/tasks.json` mínimo (T1 fix, T2 verify/regressão).
 4. **Fix cirúrgico:** implementa a mudança mínima que resolve o sintoma — sem refatoração, sem hardening fora de escopo.
 5. **Test loop:** `morph-spec verify {feature-name} {task} --json` focado no blast radius até verde; evidência real capturada no `recap.md`.
-6. **Gate 3 sempre humano:** `morph-spec gate-decision {feature-name} review --pause true ...` → `4-review/review-report.md` → `AskUserQuestion` sempre. **Nunca** `morph-spec approve {feature-name} review --mode auto` — o CLI recusa essa combinação num hotfix.
+6. **Gate 3 sempre humano:** `morph-spec gate-check {feature-name} review` (força a pausa via `workType: hotfix`, lido do disco) → `4-review/review-report.md` → `AskUserQuestion` sempre. **Nunca** `morph-spec approve {feature-name} review --mode auto` — o CLI recusa essa combinação num hotfix.
 7. **Pós-gate:** `morph-spec verify {feature-name}` (suíte completa da feature) e sinaliza commit/archive — não arquiva automaticamente.
 
 ## Anti-padrões

package/framework/docs/CLI.md

@@ -6,10 +6,11 @@
 
 ## 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-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`** — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
+- **`morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate.
+- **`morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`** — o **escape manual**: registra uma decisão já tomada pela sessão (ex.: `discoveryMode: "interview"`, sinal que `shouldPauseGate` nem representa). Mesmo write path do `gate-check` — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
 
 ## Features
 

package/framework/hooks/shared/phase-utils.js

@@ -24,7 +24,6 @@ export const PHASE_DIRS = {
 export const OUTPUT_PHASE_MAP = {
   proposal: 'proposal',
   stackScan: 'proposal',
-  migrationPlan: 'proposal',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
   uiComponents: 'uiux',
@@ -43,7 +42,6 @@ export const OUTPUT_PHASE_MAP = {
 export const FILENAME_TO_OUTPUT = {
   'proposal.md': 'proposal',
   'stack-scan.md': 'stackScan',
-  'migration-plan.md': 'migrationPlan',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
   'components.md': 'uiComponents',

package/framework/phases.json

@@ -12,7 +12,7 @@
         "Produce proposal.md and reach Gate 1"
       ],
       "requiredOutputs": ["proposal"],
-      "optionalOutputs": ["migrationPlan", "stackScan"],
+      "optionalOutputs": ["stackScan"],
       "pausePoints": [
         { "id": "proposal", "label": "Gate 1 — Approve proposal" }
       ],
@@ -33,7 +33,7 @@
       "pausePoints": [
         { "id": "uiux", "label": "Approve UI/UX" }
       ],
-      "skill": null
+      "skill": "morph-uiux"
     },
     "plan": {
       "id": "plan",

package/framework/rules/morph-workflow.md

@@ -64,7 +64,7 @@ All outputs go in `.morph/features/{feature}/`:
 
 | Phase | Path |
 |-------|------|
-| Proposal | `0-proposal/proposal.md`, `stack-scan.md`, `migration-plan.md` (optional) |
+| Proposal | `0-proposal/proposal.md`, `stack-scan.md` |
 | Design (optional) | `1-design/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
 | Plan | `2-plan/spec.md`, `mandate.md`, `tasks.json`, `decisions.md` |
 | Implement | `3-implement/recap.md` + source code |

package/framework/schemas/feature.schema.json

@@ -145,6 +145,18 @@
       },
       "additionalProperties": false
     },
+    "verification": {
+      "type": "object",
+      "description": "The single latest deterministic verify stamp (any scope), written ONLY by `morph-spec verify`. Distinct from `verifications`/`taskVerifications` above (per-scope history with attempts/nodes): this is overwritten by every verify call regardless of scope, carrying just enough to correlate a pass/fail with the exact commit it covers. Primary consumer: `morph-spec gate-check`, which surfaces it as a signal (informational — no shouldPauseGate rule keys on it directly).",
+      "required": ["status", "sha", "ts", "scope"],
+      "properties": {
+        "status": { "type": "string", "enum": ["pass", "fail"] },
+        "sha": { "type": ["string", "null"], "description": "HEAD commit SHA at verify time (git rev-parse HEAD); null when not in a git repo or no commits yet." },
+        "ts": { "type": "string", "format": "date-time", "description": "Server-side timestamp, same instant as the corresponding verifications/taskVerifications entry's updatedAt." },
+        "scope": { "type": "string", "description": "'feature', or 'task:<id>' for a task-scoped verify." }
+      },
+      "additionalProperties": false
+    },
     "tasks": {
       "type": "object",
       "description": "Aggregate task counters (informational — the source of truth is 2-plan/tasks.json).",

package/framework/skills/README.md

@@ -13,7 +13,7 @@ These are the only skills the harness needs. MORPH.md references them by path.
 | Skill                | Purpose                                                              | User-invocable |
 |----------------------|----------------------------------------------------------------------|----------------|
 | `morph-brainstorming` | Business understanding + brownfield scan → proposal.md (Gate 1)     | yes            |
-| `morph-stack-scan`    | Detect stack drift in existing projects, generate migration-plan.md  | yes            |
+| `morph-stack-scan`    | Detect stack drift in existing projects, report in stack-scan.md     | yes            |
 | `morph-plan`          | Produce spec.md + mandate.md + tasks.json (Gate 2)                   | yes            |
 | `morph-implement`     | Execute each task with standard + persona, auto-advance between tasks| no             |
 | `morph-eval`          | Score work 0-10 across 4 dimensions, silence on score >= 9           | no             |

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.18.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.18.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.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-apply
@@ -210,21 +210,16 @@ Quando `getPendingTasks(data).length === 0`:
 
 ### 5. Gate 3 (trust-aware)
 
-Sinais de risco para Gate 3:
-
-- Score médio < 9 no review-report.
-- Presença de erros não resolvidos.
-- Mudanças incidentais em standards/.morph/framework/.
-
-Mesma lógica do Gate 1/Gate 2 (regras da tabela do MORPH.md §5, aplicadas em linguagem natural — sem scripts): `trust: manual` → pausa sempre; `standardsViolations` não-vazio → pausa; `evalScore < 9` → pausa; caso contrário → auto-passa.
-
-**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 — erro "file modified since read"):
+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-decision {feature} review --pause false --reason "score 9.2, sem violações" --signals '{"evalScore":9.2,"standardsViolations":[]}'
+morph-spec gate-check {feature} review --signals '{"evalScore":9.2,"standardsViolations":[]}'
 ```
 
-O comando grava `gateDecisions.review = { pause, reason, signals, trust, decidedAt }` no `feature.json` autoritativo com timestamp server-side (o `signals.evalScore` aqui é o score composto do review-report; shape canônico em `.morph/framework/schemas/feature.schema.json`). O hook `gate-guard.js` confere depois se a ação bateu. Sem o registro o guard não verifica.
+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.
@@ -242,7 +237,7 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 - Não dispachar mais que 4 agentes em paralelo (sobrecarga de contexto + custo).
 - Não dispachar um agente inteiro para uma raiz de effort S — overhead > trabalho; o `morph-spec dag` já as marca como `inline`.
 - Não deixar sub-agent tocar `tasks.json`, `feature.json` ou o board de sessão — estado é do orquestrador (cláusula 2 do protocolo).
-- Não editar `feature.json` à mão para gravar scores ou decisões de gate — use `morph-spec score` e `morph-spec gate-decision` (timestamps server-side; o Edit manual colide com o hook state-sync — "file modified since read").
+- Não editar `feature.json` à mão para gravar scores ou decisões de gate — use `morph-spec score` e `morph-spec gate-check`/`gate-decision` (timestamps server-side; o Edit manual colide com o hook state-sync — "file modified since read").
 
 ## Output esperado
 
@@ -262,5 +257,6 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 - `morph-spec dag {feature}` — análise de DAG e decisão sequencial vs paralelo (ponderada por effort), incluindo recomendação de isolamento (`isolation.recommended: "worktree"`)
 - `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores (código antes do juiz)
 - `morph-spec score {feature} {task} {score} [--dims a,c,q,t]` — grava taskScores no feature.json com timestamp server-side
-- `morph-spec gate-decision {feature} {gate} --pause {bool} [--reason ...] [--signals ...]` — grava gateDecisions no feature.json com timestamp server-side (shape em `.morph/framework/schemas/feature.schema.json`)
+- `morph-spec gate-check {feature} {gate} [--json]` — default: coleta sinais do disco, decide via `shouldPauseGate`, persiste `gateDecisions`
+- `morph-spec gate-decision {feature} {gate} --pause {bool} [--reason ...] [--signals ...]` — escape manual: risco que o `gate-check` não vê no disco (shape em `.morph/framework/schemas/feature.schema.json`)
 - `.morph/framework/MORPH.md` §5 — regras de pausa de gate (trust mode)

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.18.0"
+cliVersion: "8.20.0"
 ---
 
 # morph-brainstorming
@@ -40,7 +40,7 @@ Fato não se pergunta. Antes de levar a primeira pergunta ao usuário, levante o
 
 3. Reconciliação de design-system (se aplicável): comparar `.morph/context/design-system.md` (se existir) com o que foi detectado no stack-scan e com bundles/mocks recentes do usuário. Se houver **divergência** (tokens diferentes, framework version mismatch, fonte aprovada distinta), marque `signals.designSystemDivergence = true` — a escolha da fonte vira uma **decisão da árvore** (Parte 1), não uma pergunta solta. Resolvida, atualize `.morph/context/design-system.md` com a fonte escolhida + entrada de changelog (data, motivo).
 
-4. Desvio de stack detectado: gere `migration-plan.md` em `.morph/features/{feature}/0-proposal/`. "A migração entra nesta feature ou vira feature separada?" também é decisão da árvore.
+4. Desvio de stack detectado (`stack-scan.md`, seção Desvios): "a migração entra nesta feature ou vira feature separada?" — pergunta feita pelo `morph-stack-scan` ao fim da varredura — também é decisão da árvore; a resposta vai para a seção "Compliance de stack" do `proposal.md` (Parte 4).
 
 ### Parte 1 — Árvore de decisões abertas
 
@@ -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
@@ -102,27 +102,17 @@ options:
 
 2. Apresente o Gate 1 segundo o modo de descoberta e o trust mode.
 
-   Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular os sinais de risco em linguagem natural — sem scripts:
-
-   - `discoveryMode` = `"interview"` ou `"auto"`, conforme a resposta da Parte 2.
-   - `designSystemDivergence` = detectado na Parte 0 (fontes de design conflitantes).
-   - `standardsViolations` = lista de violações detectadas.
-
-   **Decisão de pausa** (regras da tabela do MORPH.md §5): **modo entrevista → pausa sempre** ("não aja até eu confirmar" é literalmente o Gate 1: a confirmação do entendimento compartilhado é o gate); `trust: manual` → pausa sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → auto-passa (`pause: false`). Monte `reason` com o sinal que disparou.
-
-   **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"):
-
+   **Modo entrevista** (Parte 2) é a única exceção genuína: pausa sempre, e `shouldPauseGate` não tem esse conceito — `discoveryMode` não está entre as chaves que `gate-check --signals` aceita sobrescrever. Registre direto, sem `gate-check`:
    ```
-   # modo entrevista — o gate pausa sempre
-   morph-spec gate-decision {feature} proposal --pause true --reason "modo entrevista — entendimento compartilhado confirmado pelo usuário" --signals '{"discoveryMode":"interview","designSystemDivergence":false,"standardsViolations":[]}'
-
-   # modo automático, sem sinais de risco
-   morph-spec gate-decision {feature} proposal --pause false --reason "nenhum sinal de risco" --signals '{"discoveryMode":"auto","designSystemDivergence":false,"standardsViolations":[]}'
+   morph-spec gate-decision {feature} proposal --pause true --reason "modo entrevista — entendimento compartilhado confirmado pelo usuário" --signals '{"discoveryMode":"interview"}'
    ```
 
-   `signals` é free-form no `feature.schema.json` — `discoveryMode` não exige mudança de schema, e deixa o modo escolhido auditável no `feature.json` commitado.
+   **Fora do modo entrevista** (o caminho comum), rode `morph-spec gate-check {feature} proposal [--json]` — lê `trust` de `.morph/config/config.json`, decide via `shouldPauseGate` e persiste `gateDecisions.proposal` com timestamp server-side, imprimindo `pause`/`reason`/`signals`. Se a Parte 0 detectou divergência de design-system (leitura semântica — o `gate-check` não a vê sozinho no disco), repasse-a: `designSystemDivergence` é uma das poucas chaves que `--signals` aceita sobrescrever aqui:
+   ```
+   morph-spec gate-check {feature} proposal --signals '{"designSystemDivergence":true}'
+   ```
 
-   O comando grava `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt }` no `feature.json` autoritativo com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
+   **Nunca edite `feature.json` à mão** (o Edit manual colide com o hook state-sync — erro "file modified since read"). Os dois comandos gravam `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt }` no mesmo lugar (shape canônico em `.morph/framework/schemas/feature.schema.json`); o hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com a decisão persistida.
 
    **Se `pause === true`** (manual mode OU risco detectado em auto), use `AskUserQuestion`:
 
@@ -152,8 +142,7 @@ options:
    No caminho manual, o hook state-sync.js detecta a aprovação automaticamente (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`) — **atribuindo pela feature nomeada na pergunta**; sem o nome, e com mais de uma feature na árvore, ele recusa a gravar e avisa (aprove então por `morph-spec approve {feature} proposal`). Em modo auto sem AskUserQuestion, aprove via `morph-spec approve {feature} proposal --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta 2-plan/) — nunca via Edit à mão de state.json.
 
 ## Output esperado
-- `.morph/features/{feature}/0-proposal/proposal.md` — proposta aprovada
-- `.morph/features/{feature}/0-proposal/migration-plan.md` — apenas se houver desvio de stack
+- `.morph/features/{feature}/0-proposal/proposal.md` — proposta aprovada, com desvios de stack (se houver) resolvidos na seção "Compliance de stack"
 - Gate 1 apresentado e aprovado
 
 ## Referências