@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/framework/skills/level-0-meta/{post-implementation → morph-post-implementation}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: post-implementation
+name: morph:post-implementation
 description: Orquestra o fluxo completo pós-implementação: detecção de stack,
   scans automáticos (C#/Next.js), testes, validate-feature, smoke test via
   Playwright (obrigatório se dev server ativo), checklist de code review por
@@ -28,7 +28,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task,
 ## Step 1 — Detectar Stack
 
 ```bash
-node .claude/skills/post-implementation/scripts/detect-stack.mjs
+node .claude/skills/morph-post-implementation/scripts/detect-stack.mjs
 ```
 
 Output JSON: `{ stack: "DOTNET" | "NEXTJS" | "FULLSTACK" | "UNKNOWN", frontendPath, backendPath, startCommand }`
@@ -49,20 +49,20 @@ Execute os scans automáticos conforme o stack detectado.
 ### Se DOTNET ou FULLSTACK:
 
 ```bash
-node .claude/skills/code-review/scripts/scan-csharp.mjs --diff
+node .claude/skills/morph-code-review/scripts/scan-csharp.mjs --diff
 ```
 
 ### Se NEXTJS ou FULLSTACK:
 
 ```bash
-node .claude/skills/code-review-nextjs/scripts/scan-nextjs.mjs --diff
+node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs --diff
 ```
 
 **🚫 BLOCK se qualquer finding CRITICAL encontrado.**
 
 Corrija todos os CRITICALs antes de continuar. Para revisar a lista completa de checks:
-- .NET: `/code-review`
-- Next.js: `/code-review-nextjs`
+- .NET: `/morph:code-review`
+- Next.js: `/morph:code-review-nextjs`
 
 ---
 
@@ -109,7 +109,7 @@ Leia o output de validação, corrija os issues reportados e re-execute até pas
 ### 5a. Detectar Dev Server
 
 ```bash
-node .claude/skills/post-implementation/scripts/detect-dev-server.mjs "<startCommand>"
+node .claude/skills/morph-post-implementation/scripts/detect-dev-server.mjs "<startCommand>"
 ```
 
 Passe o `startCommand` retornado pelo detect-stack no Step 1.
@@ -140,7 +140,7 @@ await mcp__playwright__browser_console_messages({ level: 'error' });
 // Screenshot para documentação
 await mcp__playwright__browser_take_screenshot({
   type: 'png',
-  filename: '.morph/features/$ARGUMENTS/4-implement/smoke-screenshots/smoke-<timestamp>.png'
+  filename: '.morph/features/$ARGUMENTS/5-implement/smoke-screenshots/smoke-<timestamp>.png'
 });
 ```
 
@@ -181,7 +181,7 @@ Não é possível prosseguir para criação de PR sem smoke test ou confirmaçã
 
 ## Step 6 — Code Review Checklist (CRITICAL + HIGH)
 
-> Antes de revisar, leia: `.claude/skills/code-review/references/review-guidelines.md` — aplique confidence ≥ 75, ignore violações pré-existentes, inclua file:line em cada finding.
+> Antes de revisar, leia: `.claude/skills/morph-code-review/references/review-guidelines.md` — aplique confidence ≥ 75, ignore violações pré-existentes, inclua file:line em cada finding.
 
 Revise os itens mais importantes por stack. Para review completo, use os skills dedicados.
 
@@ -191,14 +191,14 @@ Dispatch dois subagents em paralelo (Task tool):
 
 **Subagent 1 — Backend Review:**
 > Revisor .NET focado. Escopo: APENAS arquivos .cs alterados (git diff main...HEAD).
-> Run: `node .claude/skills/code-review/scripts/scan-csharp.mjs --diff`
+> Run: `node .claude/skills/morph-code-review/scripts/scan-csharp.mjs --diff`
 > Depois revisar manualmente itens CRITICAL+HIGH do checklist .NET.
 > Aplicar review-guidelines.md: confidence ≥ 75, skip pré-existentes.
 > Output: findings com file:line, ou "✅ Sem CRITICAL/HIGH em backend alterado."
 
 **Subagent 2 — Frontend Review:**
 > Revisor Next.js focado. Escopo: APENAS arquivos .tsx/.ts alterados (git diff main...HEAD).
-> Run: `node .claude/skills/code-review-nextjs/scripts/scan-nextjs.mjs --diff`
+> Run: `node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs --diff`
 > Depois revisar manualmente itens CRITICAL+HIGH do checklist Next.js.
 > Aplicar review-guidelines.md: confidence ≥ 75, skip pré-existentes.
 > Output: findings com file:line, ou "✅ Sem CRITICAL/HIGH em frontend alterado."
@@ -222,14 +222,14 @@ Aguardar ambos. **🚫 BLOCK se algum retornar CRITICAL não resolvido.**
 [ ] DTOs com nomes descritivos + tipos corretos
 ```
 
-> Para lista completa: `/code-review`
+> Para lista completa: `/morph:code-review`
 
 ### Se NEXTJS:
 
 **Itens CRITICAL e HIGH — Next.js:**
 
 ```
-[ ] node .claude/skills/code-review-nextjs/scripts/scan-nextjs.mjs --diff → 0 CRITICAL
+[ ] node .claude/skills/morph-code-review-nextjs/scripts/scan-nextjs.mjs --diff → 0 CRITICAL
 [ ] File names em kebab-case (user-card.tsx, não UserCard.tsx)
 [ ] 'use client' apenas em componentes com hooks/event handlers
 [ ] Sem useEffect para data fetching → Server Component ou useQuery
@@ -241,7 +241,7 @@ Aguardar ambos. **🚫 BLOCK se algum retornar CRITICAL não resolvido.**
 [ ] Sem any type annotation
 ```
 
-> Para lista completa: `/code-review-nextjs`
+> Para lista completa: `/morph:code-review-nextjs`
 
 **🚫 BLOCK se qualquer item CRITICAL não estiver resolvido.**
 
@@ -259,7 +259,52 @@ npx morph-spec generate recap $ARGUMENTS
 
 ---
 
-## Step 8 — PR Suggestion
+## Step 8 — Finish Worktree
+
+Implementation is complete. If the feature was developed in a morph worktree, finalize it now.
+
+**Check if a worktree exists:**
+```bash
+git worktree list | grep morph/
+```
+
+**If a `morph/{feature}` worktree exists:**
+
+Invoke the finishing-a-development-branch skill:
+```
+Skill(superpowers:finishing-a-development-branch)
+```
+
+This skill will:
+1. Verify tests pass
+2. Present 4 options:
+   - **Merge locally** → merge into base branch + delete worktree
+   - **Push and create PR** → push branch + create GitHub PR (keeps worktree)
+   - **Keep as-is** → no action (worktree preserved for later)
+   - **Discard** → delete branch + worktree (requires typed confirmation)
+3. Clean up worktree for options 1 and 4
+
+**If NOT in a worktree** (legacy mode): skip this step and proceed to Step 9.
+
+> **Note:** If the `superpowers` plugin is not installed, create the PR manually:
+> `gh pr create --title "feat({feature}): <description>" --body "..."`
+
+---
+
+## Step 9 — Pre-PR Compliance Checklist
+
+Antes de criar o PR, invoque o checklist de compliance:
+
+```
+Skill(morph:checklist)
+```
+
+Este skill verifica: segurança, SEO, performance, acessibilidade e conformidade LGPD.
+**🚫 BLOCK se qualquer item CRITICAL não estiver resolvido.**
+
+---
+
+## Step 10 — PR Suggestion
 
 Quando todos os steps passarem, sugira o PR:
 
@@ -307,6 +352,8 @@ EOF
 | Step 5 | Dev server ativo + smoke test com falha |
 | Step 5 | Dev server não detectado sem confirmação explícita do usuário |
 | Step 6 | Qualquer item CRITICAL não resolvido no checklist manual |
+| Step 8 | Tests failing in worktree before merge/PR |
+| Step 9 | Item CRITICAL no `morph:checklist` não resolvido |
 
 **Todos os BLOCKs devem ser resolvidos antes de criar o PR.**
 

package/framework/skills/level-0-meta/morph-replicate/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: morph-replicate
+name: morph:replicate
 description: Simplified workflow for converting HTML prototypes into functional Blazor components, extracting design patterns and mapping HTML elements to Fluent UI/MudBlazor equivalents. Use when an approved HTML prototype exists and needs conversion to Blazor without a full MORPH-SPEC spec pipeline.
 user-invocable: true
 argument-hint: "[feature-name] [prototype-path]"
@@ -14,12 +14,12 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ## Comando
 
 ```bash
-/morph-replicate {feature-name} {prototype-path}
+/morph:replicate {feature-name} {prototype-path}
 ```
 
 **Exemplo:**
 ```bash
-/morph-replicate ui-redesign prototipo/
+/morph:replicate ui-redesign prototipo/
 ```
 
 ---
@@ -154,7 +154,7 @@ Este workflow gera apenas:
 ## Exemplo de Execucao
 
 ```markdown
-/morph-replicate checkout-redesign prototipo/checkout/
+/morph:replicate checkout-redesign prototipo/checkout/
 
 📁 Analisando prototipo em prototipo/checkout/...
 
@@ -197,7 +197,7 @@ Mapeamento HTML → Blazor:
 
 ## Quando Usar
 
-- ✅ Prototipo HTML pronto (Figma export, hand-coded, etc.)
+- ✅ Prototipo HTML pronto (hand-coded, exported, etc.)
 - ✅ Design ja aprovado pelo cliente
 - ✅ Apenas conversao visual (sem logica de negocio nova)
 - ✅ Codigo Blazor existente para atualizar

package/framework/skills/level-0-meta/morph-replicate/references/blazor-html-mapping.md

@@ -1,7 +1,7 @@
 # HTML → Blazor Component Mapping Reference
 
 > Reference for converting HTML prototype elements to Fluent UI / MudBlazor equivalents.
-> Used during FASE 1 of the `/morph-replicate` workflow.
+> Used during FASE 1 of the `/morph:replicate` workflow.
 
 ## Common Component Mappings
 

package/framework/skills/level-0-meta/{simulation-checklist → morph-simulation-checklist}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: simulation-checklist
+name: morph:simulation-checklist
 description: Checklist for implementing mock/simulation clients for external .NET services (AI APIs, payments, email). Use when setting up simulation mode without real API access, when creating fake service implementations for development/testing, or when debugging external service integrations.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

package/framework/skills/level-0-meta/{terminal-title → morph-terminal-title}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: terminal-title
+name: morph:terminal-title
 description: Manually set the terminal window title for the current task. Use when you need to override the automatic title set by the hook, or to set a specific descriptive title for the current work context.
 argument-hint: "[title]"
 user-invocable: true
@@ -46,7 +46,7 @@ Fix: Auth Login Bug
 Run the title script with the desired title:
 
 ```bash
-bash .claude/skills/terminal-title/scripts/set_title.sh "Fix: Auth Login Bug"
+bash .claude/skills/morph-terminal-title/scripts/set_title.sh "Fix: Auth Login Bug"
 ```
 
 No confirmation needed — executes silently in the background.

package/framework/skills/level-0-meta/{tool-usage-guide → morph-tool-usage-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: tool-usage-guide
+name: morph:tool-usage-guide
 description: Decision flowchart and per-phase reference for selecting the right Claude Code tool (Read, Grep, Glob, Bash, Task) or MCP tool in MORPH-SPEC workflows. Use when unsure which tool to use for a given action, when choosing between native tools and MCPs, or when deciding whether to use a subagent vs direct tools.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
@@ -137,7 +137,7 @@ Critério: se a leitura de arquivo B não depende do CONTEÚDO de arquivo A, lei
 |------|----------------|---------------------|
 | Proposal | GitHub (opcional) | Não |
 | Setup | GitHub (opcional) | Não |
-| UI/UX | Playwright, Figma, Context7 | Não |
+| UI/UX | Playwright, Context7 | Não |
 | Design | Supabase, Context7, GitHub | Sim (domain-architect + schema em paralelo) |
 | Clarify | Context7, GitHub | Não |
 | Tasks | Context7, GitHub | Sim (quando spec tem 20+ reqs ou 3+ domínios) |
@@ -167,7 +167,6 @@ Critério: se a leitura de arquivo B não depende do CONTEÚDO de arquivo A, lei
 |-----|-------------|----------|
 | **Supabase** | Schema analysis, migrations, RLS | Grep + Read code files |
 | **GitHub** | Issues, PRs, repo metadata, code search | Bash `gh` CLI |
-| **Figma** | Design tokens, component specs | Read CSS/SCSS files |
 | **Context7** | Library documentation lookups | WebSearch + WebFetch |
 | **Playwright** | Browser automation, screenshots, page inspection, smoke tests | WebFetch (read-only), Manual testing |
 | **Azure** | Cloud resource management | Bash `az` CLI |
@@ -216,7 +215,7 @@ For the canonical list of MCPs, their tools, phase relevance, and fallbacks, see
 |-------|-------------|----------|
 | Proposal | Context7 | WebSearch |
 | Setup | GitHub | `gh` CLI |
-| UI/UX | Playwright, Figma, Context7 | WebFetch, Read CSS |
+| UI/UX | Playwright, Context7 | WebFetch, Read CSS |
 | Design | Supabase, Context7, GitHub | Grep + Read code |
 | Clarify | Context7, GitHub | WebSearch |
 | Tasks | Context7, GitHub | WebSearch, `gh` CLI |

package/framework/skills/level-0-meta/{tool-usage-guide → morph-tool-usage-guide}/references/tools-per-phase.md

@@ -17,7 +17,7 @@
 | Detect project stack | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | agents.json is the source of truth |
 | Research external requirement | **WebSearch** | Current information needed |
 | Render proposal template | **Bash** `npx morph-spec template render docs/proposal ...` | CLI command |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output {feature} proposal` | CLI command |
 
 **MCPs used:** None typically. GitHub MCP if feature comes from an issue.
 
@@ -62,7 +62,6 @@
 | Read user-provided screenshots | **Read** (image files) | Claude Code reads images natively |
 | Search for existing CSS variables | **Grep** `--root:` or `--color-` in `*.css,*.scss` | Find existing design tokens |
 | Find existing UI components | **Glob** `**/Components/**/*.razor` or `**/components/**/*.tsx` | Existing patterns |
-| Get Figma design tokens | **Figma MCP** `get_file({ fileKey })` | Extract colors, typography from Figma |
 | Look up component library API | **Context7 MCP** `query_docs({ libraryId, query })` | Accurate component props/events |
 | 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 |
@@ -70,9 +69,9 @@
 | Search for design references | **WebSearch** + **WebFetch** | External inspiration |
 | Render UI templates | **Bash** `npx morph-spec template render docs/ui-mockups ...` | CLI command |
 | Generate design system from CSS | **Bash** `npx morph-spec generate design-system --scan` | CLI command |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output {feature} uiDesignSystem && npx morph-spec state mark-output {feature} uiMockups && npx morph-spec state mark-output {feature} uiComponents && npx morph-spec state mark-output {feature} uiFlows` | CLI command |
 
-**MCPs used:** Figma (design tokens), Playwright (live preview, page inspection), Context7 (component docs).
+**MCPs used:** Playwright (live preview, page inspection), Context7 (component docs).
 
 **Anti-patterns:**
 - ❌ WebSearch for MudBlazor docs (use Context7 MCP — more accurate)
@@ -104,7 +103,7 @@
 | Render spec template | **Bash** `npx morph-spec template render docs/spec ...` | CLI command |
 | Render decisions template | **Bash** `npx morph-spec template render docs/decisions ...` | CLI command |
 | Create schema-analysis.md | **Write** to output directory | Document findings |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output {feature} schemaAnalysis && npx morph-spec state mark-output {feature} spec && npx morph-spec state mark-output {feature} contracts && npx morph-spec state mark-output {feature} decisions` | CLI command |
 
 **MCPs used:** Supabase (schema analysis), Context7 (library research), GitHub (code search).
 
@@ -133,7 +132,7 @@
 | Research edge case behavior | **WebSearch** | External knowledge for edge cases |
 | Update spec with clarifications | **Edit** spec.md | Preserve existing content, add sections |
 | Create clarifications.md | **Bash** `npx morph-spec template render docs/clarifications ...` | Use template |
-| Update state | **Bash** `npx morph-spec state mark-output ... clarifications` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output {feature} clarifications` | CLI command |
 
 **MCPs used:** Context7 (validate feasibility), GitHub (known issues).
 
@@ -159,6 +158,7 @@
 | Create GitHub issues from tasks | **GitHub MCP** `create_issue()` | Sync tasks to project management |
 | **Fallback:** Create issues via CLI | **Bash** `gh issue create ...` | When no GitHub MCP |
 | Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | CLI command |
+| Mark tasks output | **Bash** `npx morph-spec state mark-output {feature} tasks` | CLI command |
 | Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | CLI command |
 
 **MCPs used:** Context7 (complexity estimation), GitHub (issue creation).
@@ -195,7 +195,7 @@
 | Smoke test feature no browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual testing |
 | Verificar erros de console | **Playwright MCP** `browser_console_messages()` | Browser DevTools |
 | Screenshot para recap.md | **Playwright MCP** `browser_take_screenshot()` | Manual screenshot |
-| Update state | **Bash** `npx morph-spec state set ...` | CLI command |
+| Mark recap output | **Bash** `npx morph-spec state mark-output {feature} recap` | CLI command |
 
 **MCPs used:** Supabase (migrations, RLS), Context7 (API lookup), GitHub (PRs), Playwright (smoke test, verification).
 

package/framework/skills/level-0-meta/{verification-before-completion → morph-verification-before-completion}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: verification-before-completion
+name: morph:verification-before-completion
 description: Phase-specific verification checklists and morph-spec validation commands for confirming MORPH-SPEC outputs are complete and correct. Use before marking any task done, before advancing to the next phase, before committing, or before creating PRs.
 user-invocable: true
 argument-hint: "[feature-name] [phase?]"
@@ -9,7 +9,7 @@ argument-hint: "[feature-name] [phase?]"
 
 > Never claim work is complete without running verification. Evidence before assertions.
 >
-> **Script:** Run `node .claude/skills/verification-before-completion/scripts/check-phase-outputs.mjs <feature> [phase]` to check required output files exist.
+> **Script:** Run `node .claude/skills/morph-verification-before-completion/scripts/check-phase-outputs.mjs <feature> [phase]` to check required output files exist.
 
 ## When to Use
 

package/framework/skills/level-0-meta/{verification-before-completion → morph-verification-before-completion}/scripts/check-phase-outputs.mjs

@@ -35,10 +35,10 @@ const PHASE_OUTPUTS = {
     { file: '2-ui/flows.md', required: false },
   ],
   tasks: [
-    { file: '3-tasks/tasks.md', required: true },
+    { file: '4-tasks/tasks.md', required: true },
   ],
   implement: [
-    { file: '4-implement/recap.md', required: true },
+    { file: '5-implement/recap.md', required: true },
   ],
 };
 

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

@@ -0,0 +1,238 @@
+---
+name: morph:phase-clarify
+description: MORPH-SPEC Phase 3 (Clarify). Iterative clarification loop driven by a satisfaction score (0-100). Generates targeted questions per round, always presents "Encerrar Clarify" as exit option, and stops when score ≥ 85 or user exits. Use after design approval to eliminate spec ambiguities before task breakdown begins.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.10.0"
+---
+
+# MORPH Clarify - FASE 3
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Elimine ambiguidades da especificação através de um loop iterativo de perguntas até que o spec tenha qualidade suficiente para gerar tasks.
+
+## Pré-requisitos
+
+- [ ] FASE 2 (Design) concluída
+- [ ] `spec.md` aprovado pelo usuário
+- [ ] `contracts.cs` definidos
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
+> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
+
+| Ação | Ferramenta |
+|------|------------|
+| Ler spec.md + contracts.cs | **Read** |
+| Verificar viabilidade técnica | **Context7 MCP** `query_docs()` |
+| Verificar issues/limitações externas | **GitHub MCP** `search_issues()` |
+| Atualizar spec com clarificações | **Edit** spec.md |
+| Criar clarifications.md | **Write** |
+| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS clarifications` |
+
+---
+
+## Sistema de Pontuação de Satisfação
+
+Antes de cada round, calcule o **Satisfaction Score (0–100)** avaliando o spec atual:
+
+| Dimensão | Pts | Critério de máxima pontuação |
+|----------|-----|------------------------------|
+| **Completude funcional** | 25 | Todos os requisitos têm critérios de aceitação mensuráveis (sem "deve", "pode", "em geral") |
+| **Cobertura de falhas** | 20 | Todos os caminhos de erro têm comportamento definido (invalid input, not found, timeout, unauthorized) |
+| **Edge cases** | 20 | Limites, estados concorrentes, inputs vazios/extremos documentados |
+| **Clareza definitória** | 20 | Nenhum termo crítico sem definição, nenhum "TBD", nenhum "a definir" |
+| **Contratos de integração** | 15 | Dependências externas têm formato de payload, erros e retry policy definidos |
+
+**Thresholds:**
+
+| Score | Ação |
+|-------|------|
+| ≥ 85 | Claude está satisfeito. Apresentar resultado e oferecer "Encerrar" como opção principal |
+| 70–84 | Continuar. Focar perguntas nas dimensões com menor pontuação |
+| < 70 | Continuar. Perguntas amplas cobrindo as maiores lacunas |
+
+> O score sobe conforme as respostas são incorporadas. Não há número máximo fixo de rounds — o loop para quando o score ≥ 85 **ou** quando o usuário escolhe encerrar.
+
+---
+
+## Workflow
+
+### Inicialização
+
+**PASSO 0 (ANTES de qualquer escrita) — Garantir fase clarify:**
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Verifique o campo `"phase"` no output:
+
+**Se `"phase": "clarify"`** → ✅ fase correta, prossiga.
+
+**Se `"phase": "design"`** → execute em sequência:
+1. `npx morph-spec approve $ARGUMENTS design`
+2. `npx morph-spec phase advance $ARGUMENTS` (→ clarify)
+
+**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+
+> **Regra:** Nunca escreva `clarifications.md` ou atualize `spec.md` enquanto a fase não for `clarify`.
+
+---
+
+Leia os arquivos base:
+- `.morph/features/$ARGUMENTS/1-design/spec.md`
+- `.morph/features/$ARGUMENTS/1-design/contracts.cs`
+- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` (se existir)
+
+Calcule o score inicial. Registre mentalmente as respostas acumuladas de rounds anteriores para não repetir perguntas já respondidas.
+
+---
+
+### Loop Principal
+
+**Repita até: score ≥ 85 OU usuário escolhe encerrar.**
+
+#### A. Calcular Score do Round Atual
+
+Pontue cada dimensão com base no spec + respostas acumuladas. Anote quais dimensões estão mais fracas — elas guiam as perguntas deste round.
+
+#### B. Identificar Questões Novas
+
+Analise apenas o que **ainda não foi respondido**. Categorize por dimensão:
+
+| Categoria | Exemplos de questões |
+|-----------|----------------------|
+| **Validação** | Limites de campo, formatos aceitos, regras de negócio |
+| **Comportamento** | O que acontece quando X falha? Estado vazio? Loading? |
+| **Prioridade** | Must-have vs nice-to-have? MVP vs v2? |
+| **Integração** | Webhook vs polling? Retry policy? Timeout? |
+| **Performance** | Volume esperado? SLA de resposta? |
+| **UX** | Mensagem de erro exibida ao usuário? Feedback visual? |
+
+#### C. Apresentar Perguntas via `AskUserQuestion`
+
+**Regras obrigatórias:**
+
+1. Use `AskUserQuestion` — **NUNCA liste perguntas como texto simples**
+2. Máximo **4 perguntas por chamada** (incluindo a opção de encerrar)
+3. Se houver mais de 3 questões novas, faça chamadas sequenciais — mas a **opção de encerrar aparece SEMPRE na última chamada de cada round**
+4. **SEMPRE inclua a seguinte pergunta como última do último batch de cada round:**
+
+```json
+{
+  "header": "Encerrar?",
+  "question": "Deseja encerrar a fase Clarify agora ou continuar refinando o spec?",
+  "multiSelect": false,
+  "options": [
+    {
+      "label": "Continuar refinando",
+      "description": "Claude identificou mais questões abertas neste round"
+    },
+    {
+      "label": "Encerrar Clarify",
+      "description": "Prosseguir para fase Tasks com o spec no estado atual"
+    }
+  ]
+}
+```
+
+> Se score ≥ 85, ajuste o label da primeira opção para: `"Continuar (opcional)"` com description: `"Score ${score}/100 — spec está satisfatório, mas você pode refinar mais"`
+
+#### D. Aguardar e Incorporar Respostas
+
+**Não avance antes de receber todas as respostas.**
+
+Após receber:
+1. Verifique se a resposta é consistente com `contracts.cs` e `schema-analysis.md`
+2. Se alguma resposta for ambígua ou contraditória → peça esclarecimento antes de atualizar
+3. Atualize `spec.md` com:
+   - Seção `## Clarifications (FASE 3)` com Q&A estruturado
+   - Atualização das seções funcionais afetadas
+   - Novos edge cases em `## Edge Cases`
+
+#### E. Verificar Condição de Saída
+
+- Usuário escolheu **"Encerrar Clarify"** → sair do loop
+- Score ≥ 85 E nenhuma questão nova identificada → sair do loop
+- Caso contrário → voltar para A
+
+---
+
+### Pós-Loop: Gerar Outputs
+
+**Passo 1: Criar `clarifications.md`**
+
+Escreva em `.morph/features/$ARGUMENTS/1-design/clarifications.md`:
+
+```markdown
+# Clarifications — {Feature Name}
+
+**Fase:** CLARIFY (Fase 3)
+**Rounds realizados:** {N}
+**Score final:** {score}/100
+**Status:** Resolvido — incorporado em spec.md
+
+---
+
+## Questions & Answers
+
+### Q{N}: {Título}
+**Question:** {pergunta}
+**Answer:** {resposta do usuário}
+**Spec Updates:** {quais seções foram atualizadas}
+**Priority:** High/Medium/Low
+**Resolved:** ✅ Yes
+
+---
+
+## Edge Cases
+
+### EC{N}: {Nome}
+**Scenario:** {quando acontece}
+**Expected Behavior:** {como o sistema reage}
+**Implementation Notes:** {dicas}
+
+---
+
+## Summary
+
+| | Count |
+|---|---|
+| Questions Answered | {N} |
+| Edge Cases Documented | {N} |
+| Spec Sections Updated | {N} |
+| Score Final | {score}/100 |
+```
+
+**Passo 2: Atualizar State**
+
+```bash
+npx morph-spec state mark-output $ARGUMENTS clarifications
+```
+
+---
+
+## Outputs Gerados/Atualizados
+
+- `.morph/features/$ARGUMENTS/1-design/spec.md` — Seção "Clarifications", edge cases, requisitos refinados
+- `.morph/features/$ARGUMENTS/1-design/clarifications.md` — Q&A estruturado com score final
+
+## Critérios de Avanço
+
+- [x] Score de satisfação ≥ 85 OU usuário optou por encerrar
+- [x] Todas as respostas são consistentes com `contracts.cs`
+- [x] `spec.md` atualizado com clarificações e edge cases
+- [x] `clarifications.md` criado com Q&A e score final
+- [x] State atualizado (`mark-output clarifications`)
+
+---
+
+```bash
+npx morph-spec phase advance $ARGUMENTS
+```
+
+Continuar automaticamente para FASE 4 (Plan) após clarifications.md gerado.

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

@@ -1,9 +1,9 @@
 ---
-name: phase-codebase-analysis
+name: morph:phase-codebase-analysis
 description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.19"
+cliVersion: "4.10.0"
 ---
 
 # MORPH Codebase Analysis - Sub-fase de DESIGN
@@ -21,7 +21,7 @@ Automatiza a análise de código existente para gerar `schema-analysis.md` com d
 
 ## 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 |