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

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.11.0",
+  "version": "8.12.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.11.0 by Polymorphism Tech*
+*morph-spec v8.12.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.11.0 by Polymorphism Tech*
+*morph-spec v8.12.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -24,6 +24,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 **SEMPRE:**
 - Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
+- Abrir toda feature `feature`/`bug` com a escolha de **modo de descoberta** (entrevista ou automático), depois de varrer o ambiente e montar a árvore de decisões abertas. **No modo entrevista, uma pergunta por chamada de `AskUserQuestion`** — o "1-4 perguntas por chamada" do bloco NUNCA é o teto da tool, não licença para agrupar a entrevista. O Gate 1 pausa sempre nesse modo.
 - Atualizar o progresso em `tasks.json` ao concluir cada task gravando apenas os campos mutáveis `status`, `outputs` e `notes` — via `Write` OU `Edit` (o hook `protect-spec-files` faz diff semântico e permite qualquer um dos dois desde que o contrato do plano permaneça congelado).
 - Apresentar gates com o template fixo definido em MORPH.md / morph-plan.
 - Registrar decisões não triviais em `decisions.md`.

package/framework/MORPH.md

@@ -28,6 +28,8 @@ Entre gates, você opera com autonomia total. O dev valida. Você executa.
 
 **Regra de ouro:** Dúvida que não bloqueia o progresso → resolver e registrar. Dúvida que bloqueia → uma pergunta, máximo.
 
+**Escopo da regra de ouro:** ela vale **entre gates** — durante plan, implement e review. Ela **não** vale na abertura de uma feature: a fase proposal pode rodar em **modo entrevista**, em que perguntar até fechar o entendimento é o comportamento desejado, escolhido pelo usuário na pergunta de abertura (`morph-brainstorming` Parte 2). Entrevistar antes de especificar é barato; descobrir o mal-entendido depois do Gate 2 não é.
+
 **Código antes do juiz:** o `morph-spec verify` é a barreira determinística e barata — build, testes e validadores estáticos rodam primeiro, sempre igual, sem custo de tokens. O juiz LLM (morph-eval) só é acionado quando o verify passa. Código é o herói não-celebrado do loop: ele pega o que pega de graça; o juiz gasta tokens só no que o código não consegue ver.
 
 ---
@@ -91,6 +93,8 @@ O fluxo padrão de uma feature tem quatro fases. Cada fase tem uma pasta dedicad
 | 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` e `bug` — `chore`/`hotfix` nascem em `implement`): **entrevista** (uma pergunta por vez até a árvore de decisões abertas zerar; Gate 1 pausa sempre, porque a confirmação do entendimento compartilhado é o gate) 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 o `morph-stack-scan` ou o acervo de use cases responde não vira pergunta ao usuário. Detalhes em `morph-brainstorming`.
+
 A fase `1-design/` (design system, mockups, flows) é opcional — aplica-se apenas a features com componentes de UI novos e deve ser explicitamente requisitada pelo usuário.
 
 Não avance de fase sem o gate correspondente ter sido confirmado.

package/framework/commands/morph-proposal.md

@@ -21,10 +21,11 @@ Conduz a feature do request inicial até o Gate 2 (plano aprovado), sem interven
    - Se não existe: criar a estrutura e seguir o passo 2.
 
 2. **Invocar `morph-brainstorming`** (skill em `framework/skills/core/morph-brainstorming/`):
-   - Faz até 4 perguntas de negócio via AskUserQuestion.
-   - Roda Explore subagent para detectar stack e estado do codebase.
+   - Varre o ambiente **antes** de qualquer pergunta (stack, contexto do projeto, acervo de use cases).
+   - Monta a árvore de decisões abertas — só o que a varredura não respondeu.
+   - Abre com a escolha de **modo de descoberta** (entrevista ou automático), recomendando um.
    - Produz `proposal.md` em `.morph/features/{feature-name}/0-proposal/`.
-   - Apresenta o **Gate 1**.
+   - Apresenta o **Gate 1** (que pausa sempre no modo entrevista).
 
 3. **Aguardar aprovação do Gate 1.**
    - Resposta válida: "aprovado", "pode avançar", "lgtm".

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.11.0"
+cliVersion: "8.12.0"
 ---
 
 # create-umbraco-lp

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.11.0"
+cliVersion: "8.12.0"
 ---
 
 # migrate-lp-to-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.11.0"
+cliVersion: "8.12.0"
 ---
 
 # morph-apply

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

@@ -1,10 +1,10 @@
 ---
 name: morph-brainstorming
-description: Entende o negócio, os usuários e a arquitetura antes de qualquer planejamento técnico. Para projetos existentes, detecta desvios de stack e propõe plano de compliance.
+description: Entende o negócio, os usuários e a arquitetura antes de qualquer planejamento técnico. Varre o ambiente primeiro, monta a árvore de decisões abertas e abre com a escolha de modo de descoberta (entrevista uma-pergunta-por-vez ou automático). Para projetos existentes, detecta desvios de stack e propõe plano de compliance.
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.11.0"
+cliVersion: "8.12.0"
 ---
 
 # morph-brainstorming
@@ -31,44 +31,72 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
 
 ## Modo bug-lean (`workType: bug`)
 
-Quando a feature tem `workType: bug` (roteada pela `morph-proposal` — ver MORPH.md §2.1 "Roteamento por tipo de trabalho"), o brainstorming é enxuto: pule as 4 perguntas de negócio da Parte 1 e faça **no máximo 1 pergunta de repro** via `AskUserQuestion` (como reproduzir, em qual ambiente) — só se isso não estiver claro no pedido original. O `stack-scan` (Parte 2) continua rodando normalmente, o diagnóstico precisa do contexto técnico. O `proposal.md` (Parte 3) foca em **Repro / Diagnóstico / Root cause provável / Escopo do fix / Critérios de aceite**, sem as perguntas de negócio completas.
+Quando a feature tem `workType: bug` (roteada pela `morph-proposal` — ver MORPH.md §2.1 "Roteamento por tipo de trabalho"), o brainstorming é enxuto. A varredura (Parte 0) continua rodando normalmente — o diagnóstico precisa do contexto técnico —, mas a árvore da Parte 1 é de **repro, diagnóstico e comportamento do sistema**, não de negócio; em modo automático (Parte 3) isso significa no máximo 1 pergunta de repro, e só se o pedido original não deixar claro. O `proposal.md` (Parte 4) foca em **Repro / Diagnóstico / Root cause provável / Escopo do fix**, sem as seções de negócio completas.
 
 Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §2.1), o fluxo completo abaixo permanece integral.
 
 ## O que fazer
 
-### Parte 1 — Entendimento de negócio
+### Parte 0 — Varredura (antes de qualquer pergunta)
 
-1. Faça até 4 perguntas ao usuário via `AskUserQuestion` para entender:
-   - Qual problema de negócio esta feature resolve?
-   - Quem são os usuários afetados e quais são os fluxos críticos deles?
-   - Qual é o critério de sucesso — como saberemos que a feature está pronta?
-   - Há integrações externas, dependências de outras features ou restrições de prazo?
+Fato não se pergunta. Antes de levar a primeira pergunta ao usuário, levante o que o ambiente já responde:
 
-   Se as respostas forem claras e suficientes, siga para a Parte 2 sem perguntas adicionais.
-
-### Parte 2 — Detecção de contexto (greenfield vs brownfield)
-
-2. Invoque `Skill(morph-stack-scan)` para detectar contexto. A skill:
+1. Invoque `Skill(morph-stack-scan)`. A skill:
    - Curto-circuita em projetos greenfield (sem source files) — retorna relatório vazio.
    - Em brownfield, varre stack atual (.csproj, package.json, migrations), padrões (Guid.NewGuid vs Guid.CreateVersion7, sealed, result pattern), features existentes.
    - Produz `.morph/features/{feature}/0-proposal/stack-scan.md`.
 
-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):
-     - Marcar `signals.designSystemDivergence = true` no contexto da feature.
-     - Perguntar ao usuário via `AskUserQuestion` qual fonte usar, listando as fontes detectadas como options.
-     - Atualizar `.morph/context/design-system.md` com a fonte escolhida + entrada de changelog (data, motivo).
+2. Leia o contexto que já existe no projeto: `.morph/context/` (se existir), `.morph/config/config.json` (stack, integrations, trust), as features ativas em `.morph/features/` e o **acervo de use cases** em `.morph/specs/usecases/`. O comportamento já implementado é o contexto mais barato que existe — e é ele que evita perguntar o que o sistema já responde.
+
+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.
+
+### Parte 1 — Árvore de decisões abertas
+
+Enumere **só o que a varredura não respondeu**. Uma decisão entra na árvore quando (a) muda o escopo, o comportamento ou a arquitetura da feature, e (b) o ambiente não a resolve.
+
+Ordene por dependência: decisão que **poda** outras vem primeiro. "O fluxo é síncrono ou assíncrono?" antecede "qual é a política de retry" — a primeira resposta pode eliminar a segunda inteira.
+
+Publique a **árvore de decisões** ao usuário antes de perguntar qualquer coisa. Ela é o sinal de progresso da entrevista e a base da recomendação de modo na Parte 2.
+
+### Parte 2 — Pergunta de abertura (modo de descoberta)
+
+Aplica-se a `workType: feature` e `bug`. **`chore` e `hotfix` não passam por aqui** — nascem com os Gates 1 e 2 carimbados `policy:{tipo}` e começam direto em `implement`.
 
-4. Com base no relatório:
-   - **Greenfield:** seguir para a Parte 3.
-   - **Stack padrão:** seguir para a Parte 3.
-   - **Desvio de stack:** gerar `migration-plan.md` em `.morph/features/{feature}/0-proposal/`. Perguntar via `AskUserQuestion`: "A migração de stack deve ser incluída nesta feature ou tratada numa feature separada?" Registrar decisão e seguir.
+Faça **uma** `AskUserQuestion` apresentando a árvore e recomendando um modo. A recomendação sai do tamanho e do acoplamento da árvore: muitas decisões abertas, ou decisões que dependem umas das outras → recomende **entrevista**; árvore rasa ou já respondida pela varredura → recomende **automático**. A opção recomendada vai em primeiro lugar, com o sufixo `(Recomendado)` no label.
 
-### Parte 3 — Produção do proposal.md
+```
+question: "Antes de começar {feature}: entrevista ou automático? Encontrei {n} decisões abertas: {resumo da árvore}"
+header: "Descoberta"
+options:
+  - { label: "{modo recomendado} (Recomendado)", description: "{por que a árvore recomenda este modo}" }
+  - { label: "{o outro modo}", description: "{o que muda na prática}" }
+```
 
-4. Produza `proposal.md` em `.morph/features/{feature}/0-proposal/` com:
+### Parte 3 — Entendimento
+
+**Modo entrevista.** Percorra a árvore, **uma pergunta por chamada** de `AskUserQuestion` — perguntas em lote desorientam e impedem que uma resposta pode ramos. Regras:
+
+- Toda pergunta traz **resposta recomendada**, como primeira opção, marcada `(Recomendado)`.
+- Cada resposta risca, poda ou abre ramos; mostre a árvore atualizada quando ela mudar de forma.
+- Fato descoberto no ambiente nunca vira pergunta. As **decisões** são do usuário; os **fatos** são seus.
+- Termina quando a árvore zera. Então apresente o **entendimento compartilhado** (problema, escopo com exclusões, usuários e fluxos, riscos) — a confirmação dele é o Gate 1, que **pausa sempre** neste modo.
+- O usuário pode encerrar a entrevista a qualquer momento; o que ficou aberto vira exclusão explícita de escopo no `proposal.md`.
+
+**Modo automático.** Até 4 perguntas via `AskUserQuestion` cobrindo o que a árvore deixou aberto:
+   - Qual problema de negócio esta feature resolve?
+   - Quem são os usuários afetados e quais são os fluxos críticos deles?
+   - Qual é o critério de sucesso — como saberemos que a feature está pronta?
+   - Há integrações externas, dependências de outras features ou restrições de prazo?
+
+   Árvore vazia → nenhuma pergunta. O Gate 1 segue trust-aware (regras do MORPH.md §5).
+
+**Em `workType: bug`**, a árvore é de **repro, diagnóstico e comportamento do sistema** — não de negócio. Em modo automático vale o bug-lean: no máximo 1 pergunta de repro, e só se o pedido original não deixar claro.
+
+### Parte 4 — Produção do proposal.md
+
+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
    - **Usuários e fluxos críticos:** quem usa e qual é o caminho principal
@@ -82,21 +110,28 @@ Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §
 
    Um bom proposal.md tem no máximo 2 páginas. Se está crescendo além disso, o escopo precisa ser cortado.
 
-5. Apresente o Gate 1 segundo trust mode.
+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:
 
-   - `designSystemDivergence` = detectado no passo 3 (fontes de design conflitantes).
+   - `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): `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.
+   **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"):
 
    ```
-   morph-spec gate-decision {feature} proposal --pause false --reason "nenhum sinal de risco" --signals '{"designSystemDivergence":false,"standardsViolations":[]}'
+   # 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":[]}'
    ```
 
+   `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.
+
    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.
 
    **Se `pause === true`** (manual mode OU risco detectado em auto), use `AskUserQuestion`:
@@ -134,5 +169,5 @@ Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §
 ## 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
-- `framework/skills/core/morph-stack-scan/SKILL.md` — invocada na Parte 2
+- `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.11.0"
+cliVersion: "8.12.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.11.0"
+cliVersion: "8.12.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.11.0"
+cliVersion: "8.12.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.11.0"
+cliVersion: "8.12.0"
 ---
 
 # morph-plan

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.11.0"
+cliVersion: "8.12.0"
 ---
 
 # morph-proposal
@@ -47,7 +47,7 @@ morph-spec create {feature-name} --request "<pedido do usuário>"
 
 - **`hotfix`** → invoque `Skill(morph-hotfix)` passando `{feature-name}` e **ENCERRE** — não siga o restante deste fluxo. A skill cuida de scout, brief, fix cirúrgico, test loop e Gate 3 (sempre humano).
 - **`chore`** → fast-track: os Gates 1 e 2 já nasceram carimbados `policy:chore` no `create`. Escreva um `2-plan/tasks.json` mínimo (1-3 tasks) e invoque `Skill(morph-apply)` diretamente — **exceção documentada** à regra do passo 7 ("não despachar `morph-apply` automaticamente"): não pausar numa mudança óbvia é exatamente o valor do fast-track.
-- **`bug`** → siga para `Skill(morph-brainstorming)` em modo **bug-lean**: produz um `proposal.md` enxuto (repro / diagnóstico / root cause / escopo / critério de aceite — não a proposta completa de uma feature nova) e depois um plano enxuto via `Skill(morph-plan)`. Gates 1 e 2 continuam trust-aware (passos 3 e 6) — só o conteúdo dos artefatos é mais curto.
+- **`bug`** → siga para `Skill(morph-brainstorming)` em modo **bug-lean**: produz um `proposal.md` enxuto (repro / diagnóstico / root cause / escopo do fix — não a proposta completa de uma feature nova; **sem critérios de aceite**, que moram na pós-condição do use case) e depois um plano enxuto via `Skill(morph-plan)`. Gates 1 e 2 continuam trust-aware (passos 3 e 6) — só o conteúdo dos artefatos é mais curto.
 - **`feature`** (default — inclui features criadas antes do v8 sem `workType`) → siga o fluxo completo abaixo (passos 1-7): brainstorming → Gate 1 → plan → Gate 2.
 
 ### 1. Determinar feature name e estado
@@ -59,20 +59,19 @@ morph-spec create {feature-name} --request "<pedido do usuário>"
 
 ### 2. Invocar `Skill(morph-brainstorming)`
 
-Passa o nome da feature. A skill:
-- Faz até 4 perguntas de negócio via `AskUserQuestion`.
-- Invoca `Skill(morph-stack-scan)` para detectar contexto (greenfield curto-circuita).
-- Detecta divergência entre fontes de design-system e marca `signals.designSystemDivergence`.
-- Produz `proposal.md` em `.morph/features/{feature}/0-proposal/`.
+Passa o nome da feature. A skill é a **dona da fase de entendimento** — não re-descreva o comportamento dela aqui. Em resumo: varre o ambiente antes de perguntar qualquer coisa (`Skill(morph-stack-scan)` + contexto do projeto + acervo de use cases), monta a **árvore de decisões abertas**, abre com a escolha de **modo de descoberta** (entrevista ou automático — só `feature` e `bug`), detecta divergência entre fontes de design-system (`signals.designSystemDivergence`) e produz `proposal.md` em `.morph/features/{feature}/0-proposal/`. Detalhes em `framework/skills/core/morph-brainstorming/SKILL.md`.
+
+No **modo entrevista** o Gate 1 pausa sempre — a confirmação do entendimento compartilhado é o gate. O modo escolhido chega ao passo 3 em `gateDecisions.proposal.signals.discoveryMode`.
 
 ### 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): `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.
+**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.
 
 **Se `pause === true`**, apresentar via `AskUserQuestion`:
 

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.11.0"
+cliVersion: "8.12.0"
 ---
 
 # morph-review

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

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

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

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

package/package.json

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

package/src/lib/validators/nextjs/next-component-validator.js

@@ -28,8 +28,34 @@ const EVENT_HANDLER_PATTERNS = [
   /\bonFocus\b/,
   /\bonBlur\b/,
   /\bonKeyDown\b/,
+  // Qualquer outro handler de evento em JSX (onMouseEnter, onKeyUp, onScroll, onDrop…).
+  // Sem isto, a lista fechada acima transforma interatividade legítima em falso-positivo.
+  /\bon[A-Z]\w*\s*=\s*\{/,
 ];
 
+/**
+ * Chamada de QUALQUER hook, não só os sete nativos: `useRouter()`, `useQuery()`, `useForm<T>()`.
+ * O `[<(]` é o que faz `useState<Record<string, string>>(` contar — um hook com argumento de
+ * tipo não casa com `useState\s*\(` e passava despercebido.
+ */
+const HOOK_CALL_PATTERN = /\buse[A-Z]\w*\s*[<(]/;
+
+/**
+ * APIs de React que só existem no cliente. `forwardRef` e `createContext` lançam em Server
+ * Component, então um módulo que os usa PRECISA da diretiva, mesmo sem hook nem handler.
+ */
+const CLIENT_ONLY_APIS = [/\bforwardRef\b/, /\bcreateContext\b/];
+
+/** Globais de browser: quem os toca não roda no servidor. */
+const BROWSER_GLOBALS = /\b(window|document|localStorage|sessionStorage|navigator)\s*[.[]/;
+
+/**
+ * Pacotes cujos componentes são client-only. O caso que mais gerava ruído é o wrapper de
+ * shadcn/Radix: ele só reexporta primitivas, então não tem hook nem handler no próprio
+ * arquivo — e era acusado para sempre, apesar de estar correto.
+ */
+const CLIENT_ONLY_IMPORTS = /from\s+['"](@radix-ui\/|sonner|@react-pdf\/|file-saver|framer-motion|motion\/|recharts|next\/navigation|react-hook-form|@tanstack\/react-query|embla-carousel|cmdk|vaul|react-day-picker|input-otp|@dnd-kit\/)/;
+
 /** Next.js special files exempt from naming checks */
 const NEXTJS_SPECIAL_FILES = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx', 'route.ts', 'middleware.ts'];
 
@@ -75,7 +101,17 @@ export function validateNextComponent(content, filePath) {
   if (hasUseClient) {
     const hasEventHandlers = EVENT_HANDLER_PATTERNS.some(pattern => pattern.test(content));
     const hasClientHooks = CLIENT_HOOKS.some(hook => new RegExp(`\\b${hook}\\b`).test(content));
-    if (!hasEventHandlers && !hasClientHooks) {
+    // Só acusa quando NENHUM sinal de necessidade de cliente aparece. Um falso-positivo aqui
+    // pede a remoção de uma diretiva que o build precisa, então a checagem erra para o lado
+    // de ficar calada.
+    const needsClient =
+      hasEventHandlers ||
+      hasClientHooks ||
+      HOOK_CALL_PATTERN.test(content) ||
+      CLIENT_ONLY_APIS.some(pattern => pattern.test(content)) ||
+      BROWSER_GLOBALS.test(content) ||
+      CLIENT_ONLY_IMPORTS.test(content);
+    if (!needsClient) {
       issues.push({
         type: 'warning',
         message: "'use client' directive present but no interactivity detected (no hooks, no event handlers)",