@polymorphism-tech/morph-spec 8.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.0"
+cliVersion: "8.12.0"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/mcp/mcp-setup.js

@@ -34,8 +34,13 @@ import { detectProject } from '../../lib/detectors/index.js';
 /**
  * Detect the current project's stack.
  * Prefers .morph/config/config.json (set during morph-spec init) over filesystem re-detection.
+ *
+ * Exported for testing: the stack decides which MCPs are relevant, and it is
+ * the one branch here worth pinning — `.morph/config/config.json` is the only
+ * place a compound stack (`dotnet-nextjs`) survives, since filesystem
+ * re-detection collapses it to whichever half it notices first.
  */
-async function detectStack(targetPath) {
+export async function detectStack(targetPath) {
   // 1. Prefer the authoritative config (handles compound stacks like nextjs+dotnet)
   try {
     const configPath = join(targetPath, '.morph', 'config', 'config.json');

package/src/core/templates/template-registry.js

@@ -151,65 +151,6 @@ export function getRequiredTemplates(stackId = null, projectPath = null) {
   return templates;
 }
 
-/**
- * Get infrastructure templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Infrastructure template array
- */
-export function getInfrastructureTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.infrastructureTemplates?.[stackId] || [];
-}
-
-/**
- * Get contract templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Contract template array
- */
-export function getContractTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.contractTemplates?.[stackId] || [];
-}
-
-/**
- * Get integration templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Integration template array
- */
-export function getIntegrationTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.integrationTemplates?.[stackId] || [];
-}
-
-/**
- * Get SaaS templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} SaaS template array
- */
-export function getSaasTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.saasTemplates?.[stackId] || [];
-}
-
-/**
- * Get example templates.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Example template array
- */
-export function getExampleTemplates(projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.exampleTemplates || [];
-}
-
 /**
  * Search templates by keyword (searches id, name, description).
  *

package/src/dashboard/scanner/hooks-scanner.js

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join, basename, dirname } from 'path';
+import { join, basename } from 'path';
+import { getHookDefinitions } from '../../utils/hooks-installer.js';
 
 function findJsFiles(dir) {
   const results = [];
@@ -25,17 +26,74 @@ function extractImports(source) {
   return imports;
 }
 
+/**
+ * Claude Code event name → the kebab-case key the Hook Inspector groups by.
+ * `pre-compact` and `teammate-idle` have no MORPH hooks — those nodes render
+ * empty on purpose.
+ */
+const EVENT_KEYS = {
+  SessionStart: 'session-start',
+  UserPromptSubmit: 'user-prompt',
+  PreToolUse: 'pre-tool-use',
+  PostToolUse: 'post-tool-use',
+  Stop: 'stop',
+  SubagentStop: 'stop',
+  PreCompact: 'pre-compact',
+};
+
+/**
+ * Build filename → [{ event, matcher }] from the installer's MORPH_HOOKS.
+ *
+ * The event is NOT derivable from the path. Before the v4→v5 migration the
+ * hooks sat in per-event folders, so `basename(dirname(file))` produced the
+ * event key; the migration flattened everything into `core/`, and from then on
+ * every hook reported `event: 'core'`. Nothing crashed — the Inspector groups
+ * by event, found no key it knew, and rendered every node empty. Twelve hooks,
+ * zero shown.
+ *
+ * `getHookDefinitions()` is the single source of truth (the same array the
+ * installer writes into settings.local.json), so the registration and the
+ * drawing can no longer disagree.
+ */
+export function hookRegistrations(definitions = getHookDefinitions()) {
+  const byFile = new Map();
+  for (const def of definitions) {
+    const key = EVENT_KEYS[def.event];
+    if (!key) continue;
+    for (const h of def.hooks || []) {
+      const file = basename(String(h.command || '').trim());
+      if (!file.endsWith('.js')) continue;
+      if (!byFile.has(file)) byFile.set(file, []);
+      byFile.get(file).push({ event: key, rawEvent: def.event, matcher: def.matcher || null });
+    }
+  }
+  return byFile;
+}
+
 export function scanHooks(frameworkDir) {
   const hooksDir = join(frameworkDir, 'hooks', 'claude-code');
   if (!existsSync(hooksDir)) return [];
-  return findJsFiles(hooksDir).map(filePath => {
+
+  const registrations = hookRegistrations();
+
+  return findJsFiles(hooksDir).flatMap(filePath => {
     const source = readFileSync(filePath, 'utf8');
-    return {
-      event: basename(dirname(filePath)),
+    const filename = basename(filePath);
+    const base = {
       name: basename(filePath, '.js'),
-      filename: basename(filePath),
-      source, imports: extractImports(source),
+      filename,
+      source,
+      imports: extractImports(source),
       description: extractJsDocDescription(source),
     };
+
+    // One entry per (file × event): telemetry-log is registered on both
+    // PostToolUse and UserPromptSubmit, and must show under both.
+    const regs = registrations.get(filename);
+    if (!regs || regs.length === 0) {
+      // On disk but never registered — real dead weight, and worth seeing.
+      return [{ ...base, event: 'unregistered', matcher: null }];
+    }
+    return regs.map(r => ({ ...base, event: r.event, rawEvent: r.rawEvent, matcher: r.matcher }));
   });
 }

package/src/dashboard/scanner/standards-scanner.js

@@ -7,9 +7,21 @@ export function scanStandards(frameworkDir, agents) {
   const sJson = JSON.parse(readFileSync(standardsJsonPath, 'utf8'));
   const refMap = {};
   for (const agent of agents) {
-    for (const std of agent.standards) {
-      if (!refMap[std.id]) refMap[std.id] = [];
-      refMap[std.id].push({ agentId: agent.id, scope: std.scope, priority: std.priority });
+    for (const std of agent.standards || []) {
+      // agents.json stores standards as plain id STRINGS. Reading `std.id` off
+      // a string yields undefined, so every reference piled into refMap
+      // [undefined] and the lookup below missed all 60 — the Standards graph
+      // drew standards with no agent edge at all. The object form is the v4
+      // shape (`{ id, scope, priority }`); still accepted so a mixed or
+      // restored agents.json does not silently lose edges again.
+      const id = typeof std === 'string' ? std : std?.id;
+      if (!id) continue;
+      if (!refMap[id]) refMap[id] = [];
+      refMap[id].push({
+        agentId: agent.id,
+        scope: typeof std === 'string' ? null : (std.scope ?? null),
+        priority: typeof std === 'string' ? null : (std.priority ?? null),
+      });
     }
   }
   const list = sJson.standards.map(std => {

package/src/lib/stack/stack-profile.js

@@ -9,7 +9,6 @@ import { join } from 'path';
  * @property {boolean} isDotnet
  * @property {boolean} isNextjs
  * @property {string[]} defaultValidators
- * @property {string[]} checkpointValidators
  * @property {string|null} buildCommand
  */
 
@@ -21,19 +20,16 @@ const PROFILES = {
   dotnet: {
     isDotnet: true, isNextjs: false,
     defaultValidators: ['architecture', 'packages'],
-    checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
     buildCommand: 'dotnet build --no-restore',
   },
   nextjs: {
     isDotnet: false, isNextjs: true,
     defaultValidators: ['nextjs-component'],
-    checkpointValidators: ['nextjs-component', 'css'],
     buildCommand: 'npx tsc --noEmit',
   },
   empty: {
     isDotnet: false, isNextjs: false,
     defaultValidators: [],
-    checkpointValidators: [],
     buildCommand: null,
   },
 };
@@ -57,7 +53,6 @@ function mergeProfiles(profiles) {
     isDotnet: profiles.some((p) => p.isDotnet),
     isNextjs: profiles.some((p) => p.isNextjs),
     defaultValidators: [...new Set(profiles.flatMap((p) => p.defaultValidators))],
-    checkpointValidators: [...new Set(profiles.flatMap((p) => p.checkpointValidators))],
     buildCommand: profiles.map((p) => p.buildCommand).find(Boolean) ?? null,
   };
 }

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)",

package/src/lib/validators/validation-runner.js

@@ -16,7 +16,11 @@ import { aggregateScores, loadRubric } from './score-aggregator.js';
 
 /**
  * Heavy validators skipped in 'light' mode (checkpoint-only).
- * Light mode runs only spec, content, and stack-specific lightweight validators.
+ *
+ * What light mode actually leaves behind is whatever the stack contributes that
+ * is NOT in this set — in practice `contrast` and `nextjs-component`. There are
+ * no `spec` or `content` validators; the switch in runSingleValidator has no
+ * case for either, and the old comment here promised both.
  */
 const HEAVY_VALIDATORS = new Set([
   'architecture', 'packages', 'contract-compliance',
@@ -49,27 +53,38 @@ export async function runValidation(projectPath, featureName, options = {}) {
     validators: {} // No validator-specific constraints
   };
 
-  // Determine which validators to run
-  const validatorIds = options.validators || detectValidators(projectPath);
+  // Determine which validators to run.
+  // COPY: the mode filter below used to splice in place, and when the caller
+  // passed `options.validators` that array WAS this array — so a light run
+  // emptied the caller's own list, and running the same list twice validated
+  // less the second time.
+  const detected = options.validators || detectValidators(projectPath);
+  let validatorIds = [...detected];
 
   // Filter by mode: 'light' skips heavy validators, 'full' (default) runs all
   const mode = options.mode || 'full';
+  const droppedByMode = [];
   if (mode === 'light') {
-    const beforeCount = validatorIds.length;
-    for (let i = validatorIds.length - 1; i >= 0; i--) {
-      if (HEAVY_VALIDATORS.has(validatorIds[i])) {
-        validatorIds.splice(i, 1);
-      }
-    }
+    validatorIds = validatorIds.filter(id => {
+      if (HEAVY_VALIDATORS.has(id)) { droppedByMode.push(id); return false; }
+      return true;
+    });
   }
 
   // Merge constraint-enabled validators
   validatorIds.push(...constraints.enabledValidators);
 
   if (validatorIds.length === 0) {
-    result.summary = 'No validators ran — no validators configured for this stack';
-    console.log(chalk.gray('\n  ℹ️  No validators configured for this stack'));
+    // Say which of the two it is. On a pure `dotnet` project every default
+    // validator is heavy, so a light run legitimately runs none — but the old
+    // message blamed the stack ("no validators configured"), which reads as
+    // "your stack has nothing to check" when the full run has two.
+    result.summary = droppedByMode.length > 0
+      ? `No validators ran — light mode skipped ${droppedByMode.length} heavy validator(s): ${droppedByMode.join(', ')}`
+      : 'No validators ran — no validators configured for this stack';
+    console.log(chalk.gray(`\n  ℹ️  ${result.summary.replace('No validators ran — ', '')}`));
     result._skipReason = result.summary;
+    result._droppedByMode = droppedByMode;
     return result;
   }
 
@@ -87,7 +102,12 @@ export async function runValidation(projectPath, featureName, options = {}) {
     // Positive check on isDotnet (contract-compliance is a VSA/.NET concern) —
     // NOT `!isNextjs`, which used to wrongly suppress it for a compound
     // "dotnet-nextjs" stack that has a .NET backend but is ALSO isNextjs.
-    if (existsSync(contractsPath) && _profileForContracts.isDotnet) {
+    // `mode: 'light'` has to hold here too. This push sits AFTER the mode
+    // filter, so contract-compliance — which is in HEAVY_VALIDATORS — used to
+    // slip into every light run that had a contracts file, making light mode
+    // heavier than declared on exactly the compound stacks it matters for.
+    const contractsIsHeavyAndSkipped = mode === 'light' && HEAVY_VALIDATORS.has('contract-compliance');
+    if (existsSync(contractsPath) && _profileForContracts.isDotnet && !contractsIsHeavyAndSkipped) {
       validatorIds.push('contract-compliance');
     }
   }

package/src/lib/validators/content/content-validator.js

@@ -1,89 +0,0 @@
-import { readFileSync, existsSync } from 'fs';
-
-/**
- * Content Validator - Validates structure and content of output files
- *
- * Ensures spec.md, tasks.json, and other outputs have required sections
- * and proper structure before allowing phase transitions.
- */
-
-/**
- * Validate spec.md structure
- * @param {string} specPath - Path to spec.md file
- * @returns {Object} Validation result
- */
-export function validateSpecContent(specPath) {
-  if (!existsSync(specPath)) {
-    return {
-      valid: false,
-      missing: ['File does not exist'],
-      errors: ['Spec file not found at: ' + specPath]
-    };
-  }
-
-  const content = readFileSync(specPath, 'utf8');
-
-  // Required sections (flexible regex handles numbered variants like '## 1. Overview')
-  const requiredSections = [
-    { label: '## Overview',                pattern: /^##\s+(?:\d+\.?\s+)?Overview/i },
-    { label: '## Functional Requirements', pattern: /^##\s+(?:\d+\.?\s+)?Functional Requirements/i },
-    { label: '## Technical',              pattern: /^##\s+(?:\d+\.?\s+)?Technical/i },
-    { label: '## Data Model',             pattern: /^##\s+(?:\d+\.?\s+)?Data Model/i },
-  ];
-
-  const lines = content.split('\n');
-  const missing = requiredSections.filter(s =>
-    !lines.some(line => s.pattern.test(line))
-  );
-
-  // Additional quality checks
-  const errors = [];
-  const warnings = [];
-
-  // Missing sections are warnings, not errors — not every spec needs all sections
-  // (e.g., frontend-only features may not have Data Model, CLI tools may not have Technical Architecture)
-  if (missing.length > 0) {
-    missing.forEach(s => {
-      warnings.push(`Missing recommended section: ${s.label}`);
-    });
-  }
-
-  // Check minimum content length
-  if (content.length < 500) {
-    warnings.push('Spec seems very short (< 500 characters). Consider adding more detail.');
-  }
-
-  // Check for placeholder text that should be replaced
-  const placeholders = ['TODO', 'TBD', 'PLACEHOLDER', '{{'];
-  placeholders.forEach(placeholder => {
-    if (content.includes(placeholder)) {
-      warnings.push(`Spec contains "${placeholder}" - ensure all placeholders are replaced`);
-    }
-  });
-
-  // Check for anti-patterns mentioned in the plan
-  if (content.toLowerCase().includes('manual azure portal')) {
-    errors.push(
-      'Spec mentions manual Azure portal creation. ' +
-      'All infrastructure must be defined in Bicep (Infrastructure as Code).'
-    );
-  }
-
-  if (content.toLowerCase().includes('create resource manually')) {
-    errors.push(
-      'Spec mentions manual resource creation. ' +
-      'Use IaC (Bicep) for all infrastructure resources.'
-    );
-  }
-
-  return {
-    valid: errors.length === 0,
-    missing,
-    errors,
-    warnings,
-    sections: {
-      required: requiredSections.length,
-      found: requiredSections.length - missing.length
-    }
-  };
-}

package/src/lib/validators/content/index.js

@@ -1,7 +0,0 @@
-/**
- * Content Validators
- *
- * Content and spec validation.
- */
-
-export * from './content-validator.js';