@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: morph:phase-plan
+description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan with exact file paths, TDD code blocks, and execution strategy analysis. Produces plan.md in 3-plan/. Use after clarify phase to create an actionable implementation plan before task breakdown.
+argument-hint: "[feature-name]"
+disable-model-invocation: true
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.10.0"
+---
+
+# MORPH Plan - FASE 4
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Gere um plano de implementacao detalhado com paths exatos, codigo TDD e estrategia de execucao.
+
+## Pre-requisitos
+
+- [ ] FASE 3 (Clarify) concluida
+- [ ] `spec.md` atualizado com clarificacoes
+- [ ] `contracts.cs` ou `contracts.ts` definidos
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+
+| Acao | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Ler spec + contracts + decisions | **Read** todos os outputs | --- |
+| Analisar codebase existente | **Glob** + **Grep** padroes | --- |
+| Consultar docs de libs | **Context7 MCP** `query_docs()` | **WebSearch** |
+| Dispatch agents para analise | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS plan` | --- |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS plan` | --- |
+
+**Anti-padroes:**
+- :x: Gerar plano sem ler contracts.cs (contracts sao a fonte de verdade!)
+- :x: Paths genericos ("adicione o arquivo") -- sempre paths exatos
+- :x: Codigo incompleto no plano ("adicione validacao") -- sempre codigo completo
+- :x: Pular analise de codebase existente (padroes existentes guiam o plano)
+- :x: Ignorar `config.architecture.style` -- VSA e DDD tem estruturas diferentes
+
+---
+
+## PRE-VOO OBRIGATORIO
+
+### 0. Garantir fase plan
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Verifique o campo `"phase"` no output:
+- `"phase": "plan"` -> fase correta, prossiga
+- qualquer outro valor -> execute `npx morph-spec phase advance $ARGUMENTS` e volte a verificar
+
+> **Regra:** Nunca escreva em `3-plan/` enquanto a fase nao for `plan`.
+
+### 1. Ler todos os prerequisitos em PARALELO
+
+```
+Read: .morph/features/{feature}/1-design/spec.md
+    + Read: .morph/features/{feature}/1-design/contracts.cs
+    + Read: .morph/features/{feature}/1-design/decisions.md
+    + Read: .morph/features/{feature}/1-design/clarifications.md
+    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (se existir)
+    + Read: .morph/config/config.json
+```
+
+### 2. Criar tasks de sessao
+
+```
+TaskCreate: "Analisar spec e planejar"        -> activeForm: "Analisando spec"
+TaskCreate: "Gerar plan.md"                   -> activeForm: "Gerando plano"
+TaskCreate: "Avanco de fase"                  -> activeForm: "Avancando fase"
+```
+
+---
+
+## Workflow
+
+### Passo 1: Analisar Feature para Contexto
+
+1. **Ler codebase existente** -- Glob para encontrar arquivos que serao modificados/criados
+2. **Identificar padroes** -- Grep por padroes similares ao que sera implementado
+3. **Verificar libs/frameworks** -- Context7 para docs das dependencias
+4. **Detectar arquitetura:**
+
+```bash
+cat .morph/config/config.json | grep -A3 '"architecture"'
+```
+
+| Valor de `config.architecture.style` | Caminho |
+|--------------------------------------|---------|
+| `"vertical-slice"` | -> Estrutura VSA: `Features/{Entity}Feature/{Op}/` |
+| qualquer outro valor | -> Estrutura DDD por layer |
+
+### Passo 2: Determinar Estrategia de Execucao
+
+Execute a analise:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS plan
+```
+
+**Fatores para recomendacao:**
+
+| Fator | Calculo |
+|-------|---------|
+| `taskCount` | Numero de requisitos funcionais + componentes tecnicos no spec |
+| `domainCount` | Dominios distintos nos activeAgents (backend, frontend, infra) |
+| `agentCount` | Total de activeAgents |
+| `independence` | % de tasks sem dependencias cross-domain |
+
+**Decisao:**
+
+| Cenario | Recomendacao |
+|---------|--------------|
+| `taskCount < 8` AND `domainCount <= 2` | **Single session** -- implementacao direta |
+| `taskCount 8-20` AND `domainCount 2-3` | **Subagent-Driven** -- um subagent morph por grupo |
+| `taskCount > 20` OR `domainCount > 3` | **Agent Teams** -- coordenacao multi-dominio |
+
+### Passo 3: Gerar `plan.md`
+
+Crie `.morph/features/$ARGUMENTS/3-plan/plan.md` com a estrutura:
+
+```markdown
+# {Feature Name} Implementation Plan
+
+> **For Claude:** Use morph:phase-implement to execute this plan.
+
+**Goal:** {Uma frase descrevendo o que sera construido}
+
+**Architecture:** {2-3 frases sobre a abordagem}
+
+**Tech Stack:** {Tecnologias chave}
+
+**Execution Strategy:** {single | subagents | agent-teams} (Recommended)
+
+---
+
+## GROUP {A} --- {Nome do Grupo}
+
+{Padrao e contexto do grupo}
+
+### {A1} --- {Nome da task}
+
+**Files:**
+- Create: `exact/path/to/file.cs`
+- Modify: `exact/path/to/existing.cs:123-145`
+- Test: `tests/exact/path/to/test.cs`
+
+**Step 1: Write the failing test**
+
+(Codigo completo do teste)
+
+**Step 2: Run test to verify it fails**
+
+Run: `{comando exato}`
+Expected: FAIL with "{mensagem}"
+
+**Step 3: Write minimal implementation**
+
+(Codigo completo da implementacao)
+
+**Step 4: Run test to verify it passes**
+
+Run: `{comando exato}`
+Expected: PASS
+
+**Step 5: Commit**
+
+git add {files}
+git commit -m "{mensagem}"
+```
+
+**Regras obrigatorias:**
+- Paths exatos SEMPRE (nunca genericos)
+- Codigo COMPLETO no plano (nunca "adicione validacao")
+- Comandos exatos com output esperado
+- DRY, YAGNI, TDD, commits frequentes
+- Cada step e uma acao de 2-5 minutos
+
+### Passo 4: Atualizar State
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS plan
+```
+
+---
+
+## PAUSA OBRIGATORIA
+
+Use `AskUserQuestion` para capturar aprovacao:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Aprovacao",
+      "question": "Plano de implementacao gerado. Aprovar para iniciar task breakdown?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Aprovar plano", "description": "Avancar para fase de task breakdown" },
+        { "label": "Tenho feedback", "description": "Digite o que deseja mudar no campo abaixo (Other)" }
+      ]
+    },
+    {
+      "header": "Execucao",
+      "question": "Qual estrategia de execucao para implementacao?",
+      "multiSelect": false,
+      "options": [
+        { "label": "{Recomendacao} (Recommended)", "description": "{Justificativa baseada na analise do Passo 2}" },
+        { "label": "{Alternativa 1}", "description": "{Descricao}" },
+        { "label": "{Alternativa 2}", "description": "{Descricao}" }
+      ]
+    }
+  ]
+}
+```
+
+> A primeira opcao de "Execucao" deve ser a recomendacao context-aware calculada no Passo 2. As alternativas sao as outras estrategias.
+
+- **"Aprovar plano"** -> execute:
+```bash
+npx morph-spec approve $ARGUMENTS plan
+npx morph-spec phase advance $ARGUMENTS
+```
+- **"Tenho feedback" ou "Other"** -> aplique o feedback recebido e repita esta PAUSA
+
+---
+
+## Outputs desta Fase
+
+<!-- morph:outputs:plan -->
+| Output | Caminho |
+|--------|---------|
+| `plan` | `.morph/features/{feature}/3-plan/plan.md` |
+<!-- /morph:outputs -->
+
+---
+
+## Criterios de Avanco
+
+- [x] `plan.md` criado com todos os grupos e tasks
+- [x] Paths exatos para todos os arquivos
+- [x] Codigo completo em cada step
+- [x] Comandos de teste com output esperado
+- [x] Estrategia de execucao definida e aprovada
+- [x] State atualizado (`mark-output plan`)
+- [x] Usuario aprovou plano
+
+---
+
+Apos aprovacao: prosseguir automaticamente para FASE 5 (Tasks).

package/framework/skills/level-1-workflows/{phase-setup → morph-phase-setup}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: phase-setup
+name: morph:phase-setup
 description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents by reading agents.json, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.19"
+cliVersion: "4.10.0"
 ---
 
 # MORPH Setup - FASE 1
@@ -21,7 +21,7 @@ Inicialize o contexto e prepare o ambiente para uma feature aprovada.
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
 > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
 
 | Ação | Ferramenta | Alternativa |
@@ -112,6 +112,49 @@ npx morph-spec state add-agent $ARGUMENTS ef-modeler
 - `.morph/context/README.md` — Overview do projeto
 - `.morph/config/config.json` — Configurações
 
+### Passo 2.5: Validar Conexoes MCP
+
+Verifique se os MCPs configurados estao funcionando antes de prosseguir.
+
+**1. Coletar MCPs recomendados:**
+- Leia `framework/phases.json` → para cada fase no workflow da feature, colete os `recommendedMCPs[]`
+- Leia `framework/skills/level-0-meta/mcp-registry.json` → obtenha os `healthCheck` de cada MCP
+
+**2. Identificar MCPs configurados:**
+- Leia `.claude/settings.local.json` → identifique quais MCPs estao em `mcpServers`
+
+**3. Para cada MCP que esta CONFIGURADO E RECOMENDADO:**
+1. Procure nas suas ferramentas disponiveis por uma que contenha `healthCheck.toolPattern` no nome
+2. Se a ferramenta existir → execute o `healthCheck.testCall` com `healthCheck.testParams`
+3. Avalie o resultado:
+
+| Resultado | Acao |
+|-----------|------|
+| **Sucesso** | `✓ {MCP} — conexao verificada` |
+| **Ferramenta nao encontrada** | `○ {MCP} — precisa restart para ativar` |
+| **Erro** | → **AskUserQuestion** com 3 opcoes (abaixo) |
+
+**Em caso de erro — pergunte ao usuario:**
+
+Use `AskUserQuestion` com header `"{MCP}"` e opcoes:
+- **Continuar sem {MCP}** — Mostre o campo `fallback` do registry e prossiga
+- **Reconfigurar credenciais** — Colete novas credenciais e atualize `.claude/settings.local.json`
+- **Parar setup** — Aborte e reporte o que precisa ser corrigido
+
+**4. Para MCPs RECOMENDADOS mas NAO CONFIGURADOS:**
+- Print `△ {MCP} — nao configurado (fallback: {registry.fallback})`
+- Sugestao: `Tip: configure com /morph:init refresh ou npx morph-spec mcp setup`
+
+**Resumo:** Mostre uma tabela com status de cada MCP antes de prosseguir:
+```
+MCP Readiness:
+  ✓ context7 — conexao verificada
+  ○ playwright — precisa restart
+  △ supabase — nao configurado (fallback: Grep + Read para schema)
+```
+
+---
+
 ### Passo 3: Confirmar Stack
 
 Baseado no proposal e contexto, confirme:
@@ -137,6 +180,10 @@ npx morph-spec dispatch-agents $ARGUMENTS design
 
 Isso informa quais agentes serão disparados em paralelo na fase de design e quais tasks eles executarão.
 
+> **Mapeamento importante:** `agents[].id` do dispatch config = `subagent_type` no `Agent` tool.
+> Exemplo: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert, prompt=agent.taskPrompt)`.
+> Cada `id` corresponde ao campo `name:` no frontmatter do arquivo em `.claude/agents/`.
+
 ### Passo 5: Atualizar State
 
 Marque a feature como na fase SETUP:

package/framework/skills/level-1-workflows/{phase-tasks → morph-phase-tasks}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: phase-tasks
+name: morph:phase-tasks
 description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ordered implementation tasks (T001...TXXX) with dependencies, checkpoints every 3 tasks, and effort estimates, producing tasks.md. Use after design and clarification phases to create a structured implementation plan before coding starts.
 argument-hint: "[feature-name]"
 disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.19"
+cliVersion: "4.10.0"
 ---
 
 # MORPH Tasks - FASE 4
@@ -22,7 +22,7 @@ Quebre a especificação em tasks executáveis, defina ordem de execução e est
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
 > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
 > **Example:** `references/tasks-example.md` — filled-in tasks.md showing expected granularity and format.
 > **Script:** `scripts/validate-tasks.mjs` — validates tasks.md structure, T### IDs, and required fields.
@@ -52,6 +52,26 @@ Quebre a especificação em tasks executáveis, defina ordem de execução e est
 
 ## ✅ PRÉ-VOO OBRIGATÓRIO (antes de iniciar breakdown de tasks)
 
+### 0. Garantir fase tasks
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Verifique o campo `"phase"` no output:
+
+**Se `"phase": "tasks"`** → ✅ fase correta, prossiga.
+
+**Se `"phase": "clarify"`** → execute em sequência:
+1. `npx morph-spec state mark-output $ARGUMENTS clarifications`
+2. `npx morph-spec phase advance $ARGUMENTS` (→ tasks)
+
+**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+
+> **Regra:** Nunca escreva em `4-tasks/` enquanto a fase não for `tasks`. O hook bloqueará a escrita.
+
+---
+
 ### 1. Ler todos os prerequisitos em PARALELO
 
 ```
@@ -98,7 +118,7 @@ TaskCreate: "Avanço de fase"                  → activeForm: "Avançando fase"
 # Verificar estado atual:
 npx morph-spec state get $ARGUMENTS
 # Verificar se design foi aprovado:
-npx morph-spec approval get $ARGUMENTS design
+npx morph-spec approval-status $ARGUMENTS
 ```
 
 ---
@@ -208,7 +228,7 @@ Para cada task, estime tempo em minutos:
 
 ### Passo 6: Gerar `tasks.md`
 
-Crie `.morph/features/$ARGUMENTS/3-tasks/tasks.md` com a estrutura completa de tasks, checkpoints e estimativas.
+Crie `.morph/features/$ARGUMENTS/4-tasks/tasks.md` com a estrutura completa de tasks, checkpoints e estimativas.
 
 ### Passo 7: Incluir Tasks de IaC (se necessário)
 
@@ -223,15 +243,32 @@ npx morph-spec state mark-output $ARGUMENTS tasks
 
 ## Outputs Gerados
 
-- `.morph/features/$ARGUMENTS/3-tasks/tasks.md` - Breakdown completo de tasks
+- `.morph/features/$ARGUMENTS/4-tasks/tasks.md` - Breakdown completo de tasks
 
 ## PAUSA OBRIGATÓRIA
 
-Apresente ao usuário 3 ações sugeridas:
+Use `AskUserQuestion` para capturar aprovação explícita antes de avançar:
+
+```json
+{
+  "questions": [{
+    "header": "Aprovação",
+    "question": "Tasks geradas. Aprovar para iniciar implementação?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Aprovar e implementar", "description": "Avançar para fase de implementação" },
+      { "label": "Tenho feedback",        "description": "Digite o que deseja mudar no campo abaixo (Other)" }
+    ]
+  }]
+}
+```
 
-1. **Aprovar breakdown e iniciar implementação**
-2. **Repriorizar tasks** - Mudar ordem de execução
-3. **Adicionar/remover tasks** - Ajustar escopo
+- **"Aprovar e implementar"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS tasks
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"Tenho feedback" ou "Other"** → aplique o feedback recebido e repita esta PAUSA
 
 ## Critérios de Avanço
 
@@ -263,7 +300,7 @@ Apresente ao usuário 3 ações sugeridas:
 <!-- morph:outputs:tasks -->
 | Output | Caminho |
 |--------|---------|
-| `tasks` | `.morph/features/{feature}/3-tasks/tasks.md` |
+| `tasks` | `.morph/features/{feature}/4-tasks/tasks.md` |
 <!-- /morph:outputs -->
 
 ---

package/framework/skills/level-1-workflows/{phase-tasks → morph-phase-tasks}/scripts/validate-tasks.mjs

@@ -7,7 +7,7 @@
  *
  * Usage:
  *   node validate-tasks.mjs <tasks-file>
- *   node validate-tasks.mjs .morph/features/my-feature/3-tasks/tasks.md
+ *   node validate-tasks.mjs .morph/features/my-feature/4-tasks/tasks.md
  *
  * Checks:
  *   - Summary table exists with T### IDs and valid statuses
@@ -57,9 +57,9 @@ if (summaryTasks.length === 0) {
   errors.push('No summary table found — expected rows matching | T### | Type | Title | Status |');
 }
 
-// 2. Parse task headers (### T001: Title)
+// 2. Parse task headers (### T001: Title  or  ### T001 — Title  or  ### T001 - Title)
 const taskHeaders = lines
-  .map((l, i) => ({ line: i + 1, match: l.match(/^###\s+(T\d{3}):\s+(.+)/) }))
+  .map((l, i) => ({ line: i + 1, match: l.match(/^###\s+(T\d{3})\s*[—–:\-]\s+(.+)/) }))
   .filter(r => r.match);
 
 // Check sequential IDs

package/framework/skills/level-1-workflows/{phase-uiux → morph-phase-uiux}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: phase-uiux
-description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md, components.md, and flows.md using Figma/Playwright/Context7 MCPs. Use after setup for features with frontend UI components, pages, dashboards, forms, wizards, or visual interactions requiring design documentation.
+name: morph:phase-uiux
+description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md, components.md, and flows.md using Playwright/Context7 MCPs. Use after setup for features with frontend UI components, pages, dashboards, forms, wizards, or visual interactions requiring design documentation.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.19"
+cliVersion: "4.10.0"
 ---
 
 # MORPH UI/UX Design - FASE 1.5
@@ -21,7 +21,7 @@ Fase condicional para features com front-end. Coleta requisitos de UI/UX, gera w
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
 > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
 
 | Ação | Ferramenta | Alternativa |
@@ -30,7 +30,6 @@ Fase condicional para features com front-end. Coleta requisitos de UI/UX, gera w
 | Ler screenshots do usuário | **Read** (arquivo de imagem) | — |
 | Buscar variáveis CSS existentes | **Grep** `--root:` em `*.css,*.scss` | — |
 | Encontrar componentes existentes | **Glob** `**/Components/**/*.razor` ou `**/components/**/*.tsx` | — |
-| Extrair design tokens do Figma | **Figma MCP** `get_file({ fileKey })` | Read CSS/SCSS variables |
 | Documentação de componentes UI | **Context7 MCP** `query_docs({ libraryId, query })` | **WebSearch** + **WebFetch** |
 | Preview de página existente | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
 | Inspecionar estrutura da página | **Playwright MCP** `browser_snapshot()` | **WebFetch** + parse manual |
@@ -40,7 +39,7 @@ Fase condicional para features com front-end. Coleta requisitos de UI/UX, gera w
 | Gerar design system de CSS existente | **Bash** `npx morph-spec generate design-system --scan` | — |
 | Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
 
-**MCPs desta fase:** Figma (design tokens), Playwright (preview, inspeção, responsividade), Context7 (docs de componentes).
+**MCPs desta fase:** Playwright (preview, inspeção, responsividade), Context7 (docs de componentes).
 
 **Anti-padrões:**
 - ❌ WebSearch para docs MudBlazor (use Context7 MCP — mais preciso)
@@ -51,7 +50,26 @@ Fase condicional para features com front-end. Coleta requisitos de UI/UX, gera w
 
 ## Workflow
 
-### Passo 0: Verificar Design System Existe
+### Passo 0: Garantir fase uiux
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Verifique o campo `"phase"` no output:
+
+**Se `"phase": "uiux"`** → ✅ fase correta, prossiga.
+
+**Se `"phase": "setup"`** → execute:
+1. `npx morph-spec phase advance $ARGUMENTS` (→ uiux)
+
+**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+
+> **Regra:** Nunca escreva em `2-ui/` enquanto a fase não for `uiux`. O hook bloqueará a escrita.
+
+---
+
+### Passo 0.5: Verificar Design System Existe
 
 **CRITICAL:** Antes de iniciar a FASE UI/UX, verifique se um design system existe:
 
@@ -252,11 +270,28 @@ estática no design, e gera screenshots dos mockups se dev server disponível.
 
 ## PAUSA OBRIGATÓRIA
 
-Apresente ao usuário 3 ações sugeridas:
+Use `AskUserQuestion` para capturar aprovação explícita antes de avançar:
+
+```json
+{
+  "questions": [{
+    "header": "Aprovação",
+    "question": "UI/UX gerado. Aprovar para avançar para design técnico?",
+    "multiSelect": false,
+    "options": [
+      { "label": "Aprovar UI/UX", "description": "Avançar para fase de design técnico" },
+      { "label": "Tenho feedback", "description": "Digite o que deseja ajustar no campo abaixo (Other)" }
+    ]
+  }]
+}
+```
 
-1. **Aprovar UI/UX e prosseguir para design técnico**
-2. **Ajustar wireframes/componentes de telas específicas**
-3. **Revisar biblioteca UI escolhida (Fluent UI / MudBlazor)**
+- **"Aprovar UI/UX"** →
+  ```bash
+  npx morph-spec approve $ARGUMENTS uiux
+  npx morph-spec phase advance $ARGUMENTS
+  ```
+- **"Tenho feedback" ou "Other"** → aplique o feedback recebido e repita esta PAUSA
 
 ## Critérios de Avanço
 

package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: morph:scope-escalation
+description: Guided workflow for mid-implementation scope escalation — analyzes complexity discovery, recommends action, and executes phase regression or task expansion
+user-invocable: true
+argument-hint: "[feature-name]"
+---
+
+# Scope Escalation Workflow
+
+Use this skill when a task during implementation reveals significantly more complexity than estimated.
+
+## Prerequisites
+
+- Feature must be in `implement` phase
+- You must have identified a specific task that triggered the discovery
+
+## Workflow
+
+### Step 1: COLLECT Evidence
+
+Ask the user (using `AskUserQuestion`):
+
+1. **Which task triggered the discovery?** (task ID from tasks.md)
+2. **What did you discover?** (specific complexity: hidden dependencies, wrong assumptions, missing abstractions)
+3. **Show evidence** — read the relevant code files to understand the actual complexity
+
+### Step 2: ANALYZE Impact
+
+Run dry-run analysis:
+
+```bash
+npx morph-spec scope escalate <feature> --task <id> --reason "<reason>" --dry-run
+```
+
+Read the recommendation output. Additionally:
+
+- Read `tasks.md` to understand which tasks are affected
+- Read `spec.md` to check if the spec assumed simpler architecture
+- Check completed tasks for potential impact
+
+### Step 3: CLASSIFY and PROPOSE
+
+Present the recommendation to the user:
+
+| Impact | Action | When |
+|--------|--------|------|
+| **Low** (1-3 tasks) | Task Expansion | The task is bigger than expected, but scope is contained |
+| **Medium** (4+ tasks, spec ok) | Regress to tasks | Multiple tasks need rewriting, but the spec is correct |
+| **High** (spec wrong) | Regress to design | The spec made incorrect assumptions about the codebase |
+
+Explain WHY you recommend this classification based on the evidence.
+
+### Step 4: APPROVE
+
+Pause and wait for user confirmation using `AskUserQuestion`:
+
+- "Do you agree with the [impact] classification?"
+- "Should we proceed with [action]?"
+- Allow override: "Or would you prefer a different target phase?"
+
+**DO NOT proceed without explicit user approval.**
+
+### Step 5: EXECUTE
+
+Based on approved action:
+
+**For expansion (low impact):**
+```bash
+npx morph-spec task expand <feature> <task-id> --into "T017a: <title>" "T017b: <title>" ...
+```
+
+**For regression (medium/high impact):**
+```bash
+npx morph-spec scope escalate <feature> --task <id> --reason "<reason>"
+```
+
+Or with target override:
+```bash
+npx morph-spec scope escalate <feature> --task <id> --reason "<reason>" --target design
+```
+
+### Step 6: GUIDE Next Steps
+
+After escalation:
+
+- **If regressed to tasks:** "Re-analyze the affected tasks. Rewrite tasks.md with accurate scope. Run `/morph-proposal <feature>` to continue from the tasks phase."
+- **If regressed to design:** "Re-analyze the spec. Update spec.md with the discovered architecture. Then regenerate tasks."
+- **If expanded:** "Continue implementing. Use `morph-spec task start <feature> <sub-task-id>` to start the first sub-task."
+
+Always remind: "Completed tasks flagged with `needsReview` should be checked for compatibility with the new scope."
+
+## Anti-Patterns
+
+- **DO NOT** skip the approval step
+- **DO NOT** escalate without evidence — read the actual code first
+- **DO NOT** regress to design when only tasks need rewriting
+- **DO NOT** expand when 4+ tasks are affected — regress instead