@polymorphism-tech/morph-spec 4.10.0 → 4.10.2

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

@@ -3,163 +3,151 @@ name: morph:phase-design
 description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads EF models/Supabase/DB, validates findings with user, then routes to VSA Blueprint or DDD Architecture Blueprint based on config.architecture.style, producing spec.md, contracts.cs, schema-analysis.md, and decisions.md through a quality loop (score 0-100). Use after setup phase to create technical specifications grounded in the real database schema.
 argument-hint: "[feature-name]"
 user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.10.0"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+cliVersion: "4.10.2"
 ---
 
-# MORPH Design - FASE 2
+# MORPH Design — Phase 2
 
 > INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
 
-Design técnico interativo: schema primeiro, blueprint validado, artefatos gerados com loop de qualidade.
+Schema-first interactive design: read the real schema, validate with user, generate blueprint, produce artifacts through a quality loop.
 
-## Pré-requisitos
+## Prerequisites
 
-- [ ] FASE 1 (Setup) concluída
-- [ ] FASE 1.5 (UI/UX) concluída OU pulada
-- [ ] Proposta aprovada pelo usuário
+- [ ] Phase 1 (Setup) completed
+- [ ] Phase 1.5 (UI/UX) completed OR skipped
+- [ ] Proposal approved by the user
 
-## Ferramentas Recomendadas
+## Recommended Tools
 
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` para guia completo.
-> **Example:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
+> **Ref:** `references/spec-example.md` — filled-in spec.md showing expected output quality.
+> **Ref:** `references/spec-authoring-guide.md` — section structure for spec.md.
 
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Ler proposal + UI specs | **Read** output files | — |
-| **Detectar arquitetura** | **Bash** `cat .morph/config/config.json \| grep -A3 '"architecture"'` | **Read** config.json |
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Read proposal + UI specs | **Read** output files | — |
+| **Detect architecture** | **Read** `.morph/config/config.json` → check `architecture.style` | **Bash** `grep` |
 | **Schema: Supabase** | **Supabase MCP** `list_tables()`, `get_table_schema()`, `get_relationships()` | — |
 | **Schema: EF Core** | **Glob** `**/Entities/**/*.cs` + **Glob** `**/*Context.cs` → **Read** | **Grep** `DbSet<` |
 | **Schema: Next.js/TS** | **Glob** `src/**/types/**/*.ts` + **Grep** `interface\|type.*=` | — |
-| Schema: políticas RLS | **Supabase MCP** `query()` com `pg_policies` | **Read** policy files |
+| Schema: RLS policies | **Supabase MCP** `query()` with `pg_policies` | **Read** policy files |
 | Dispatch vsa-architect | **Agent** `subagent_type=vsa-architect` + `prompt=agent.taskPrompt` | — |
 | Dispatch domain-architect | **Agent** `subagent_type=domain-architect` + `prompt=agent.taskPrompt` | — |
-| Dispatch tech leads | **Agent** para cada agente ativo do dispatch config | — |
-| Research biblioteca | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
-| Renderizar contracts VSA | **Bash** `npx morph-spec template render dotnet-contracts-vsa ...` | — |
-| Renderizar contracts DDD | **Bash** `npx morph-spec template render dotnet-contracts-level{N} ...` | — |
-| Renderizar spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
-| Renderizar decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
-| Atualizar state | **Bash** `npx morph-spec state mark-output $ARGUMENTS <type>` | — |
-
-**Anti-padrões:**
-- ❌ Gerar contratos antes de ler o schema real — campos adivinhados corrompem todo o design
-- ❌ Apresentar Blueprint sem validar com o usuário primeiro
-- ❌ Perguntas como texto simples — sempre use `AskUserQuestion`
-- ❌ Executar schema analysis e blueprint em sequência — são independentes, paralelize
-- ❌ Ignorar `config.architecture.style` — sempre detecte antes do CHECKPOINT 2
+| Dispatch tech leads | **Agent** for each active agent from dispatch config | — |
+| Research library | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
+| Render contracts VSA | **Bash** `npx morph-spec template render dotnet-contracts-vsa ...` | — |
+| Render contracts DDD | **Bash** `npx morph-spec template render dotnet-contracts-level{N} ...` | — |
+| Render spec.md | **Bash** `npx morph-spec template render docs/spec ...` | — |
+| Render decisions.md | **Bash** `npx morph-spec template render docs/decisions ...` | — |
+| Update state | **Bash** `npx morph-spec state mark-output $ARGUMENTS <type>` | — |
+
+**Anti-patterns:**
+- Do not generate contracts before reading the real schema — guessed field names corrupt the entire design
+- Do not present a Blueprint without validating with the user first
+- Do not ask questions as plain text — always use `AskUserQuestion`
+- Do not ignore `config.architecture.style` — always detect it before CHECKPOINT 2
 
 ---
 
-## ✅ PRÉ-VOO
+## PRE-FLIGHT
 
-**PASSO 0 (ANTES de qualquer leitura ou escrita) — Garantir fase design:**
+**STEP 0 (BEFORE any reads or writes) — Ensure phase is design:**
 
 ```bash
 npx morph-spec state get $ARGUMENTS
 ```
 
-Verifique o campo `"phase"` no output:
+Check the `"phase"` field in the output:
 
-**Se `"phase": "design"`** → ✅ fase correta, prossiga.
+**If `"phase": "design"`** → phase is correct, proceed.
 
-**Se `"phase": "proposal"`** → execute em sequência:
+**If `"phase": "proposal"`** → execute in sequence:
 1. `npx morph-spec state mark-output $ARGUMENTS proposal`
 2. `npx morph-spec phase advance $ARGUMENTS` (→ setup)
 3. `npx morph-spec phase advance $ARGUMENTS` (→ design)
 
-**Se `"phase": "setup"`** → execute:
+**If `"phase": "setup"`** → execute:
 1. `npx morph-spec phase advance $ARGUMENTS` (→ design)
 
-**Qualquer outro valor** → ⛔ não prossiga — estado inconsistente, reporte ao usuário.
+**Any other value** → do not proceed — inconsistent state, report to user.
 
-> **Regra:** Nunca escreva em `1-design/` enquanto a fase não for `design`. O hook bloqueará e a sequência ficará corrompida.
+> **Rule:** Never write to `1-design/` while the phase is not `design`. The hook will block and the sequence will be corrupted.
 
 ---
 
-Leia em paralelo:
+Read in parallel:
 ```
 Read: .morph/features/$ARGUMENTS/0-proposal/proposal.md
-    + Read: .morph/config/config.json          ← detectar architecture.style
+    + Read: .morph/config/config.json          ← detect architecture.style
     + Read: .morph/context/README.md
 ```
 
-**Detectar estilo de arquitetura:**
+**Detect architecture style:**
 
-```bash
-cat .morph/config/config.json | grep -A3 '"architecture"'
-```
-
-| Valor de `config.architecture.style` | Caminho |
-|--------------------------------------|---------|
-| `"vertical-slice"` | → **VSA** (CHECKPOINT 2-VSA + contratos VSA) |
-| qualquer outro valor ou ausente | → **DDD** (CHECKPOINT 2-DDD + contratos DDD) |
-
-Se escopo ≥ 20 tasks ou refactor toca ≥ 5 arquivos de domínio → **EnterPlanMode** antes de continuar.
+| Value of `config.architecture.style` | Path |
+|--------------------------------------|------|
+| `"vertical-slice"` | → **VSA** (CHECKPOINT 2-VSA + VSA contracts) |
+| any other value or absent | → **DDD** (CHECKPOINT 2-DDD + DDD contracts) |
 
-Crie tasks de sessão:
-```
-TaskCreate: "Analisar schema"         → activeForm: "Lendo schema real"
-TaskCreate: "Validar Blueprint"       → activeForm: "Gerando blueprint"
-TaskCreate: "Gerar spec + contracts"  → activeForm: "Gerando artefatos"
-TaskCreate: "Loop de qualidade"       → activeForm: "Refinando design"
-```
+If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode** before continuing.
 
 ---
 
-## CHECKPOINT 1 — Schema Real (OBRIGATÓRIO antes de qualquer geração)
+## CHECKPOINT 1 — Real Schema (MANDATORY before any generation)
 
-> **Regra:** Nunca assuma nomes de campos. Todo DTO gerado deve ter origem rastreável no schema.
+> **Rule:** Never assume field names. Every generated DTO must have a traceable origin in the schema.
 
-### 1.1 Ler schema real
+### 1.1 Read real schema
 
-Execute em paralelo conforme o stack detectado em `config.json`:
+Execute in parallel according to the stack detected in `config.json`:
 
-**Supabase (preferencial se disponível):**
+**Supabase (preferred if available):**
 ```
-Supabase MCP: list_tables() → get_table_schema(table) para cada tabela relevante
-            + get_relationships() → políticas RLS se aplicável
+Supabase MCP: list_tables() → get_table_schema(table) for each relevant table
+            + get_relationships() → RLS policies if applicable
 ```
 
 **EF Core (.NET):**
 ```
-Glob: **/Entities/**/*.cs  →  Read cada arquivo de entidade
-Glob: **/*DbContext.cs     →  Read para ver DbSet<> e relações
-Grep: "DbSet<"             →  confirmar entidades mapeadas
+Glob: **/Entities/**/*.cs  →  Read each entity file
+Glob: **/*DbContext.cs     →  Read to see DbSet<> and relations
+Grep: "DbSet<"             →  confirm mapped entities
 ```
 
 **TypeScript/Next.js:**
 ```
 Glob: src/**/types/**/*.ts, src/**/models/**/*.ts
-Grep: "export interface|export type" → Read arquivos encontrados
+Grep: "export interface|export type" → Read found files
 ```
 
-### 1.2 Gerar schema-analysis.md
+### 1.2 Generate schema-analysis.md
 
-Escreva `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` com:
+Write `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` with:
 
 ```markdown
 # Schema Analysis — {Feature}
 
-## Entidades Relevantes
+## Relevant Entities
 
 ### {EntityName}
-| Campo | Tipo DB | Tipo C#/TS | Nullable | Notas |
+| Field | DB Type | C#/TS Type | Nullable | Notes |
 |-------|---------|-----------|----------|-------|
 | id    | uuid    | Guid      | No       | PK    |
 | ...   | ...     | ...       | ...      | ...   |
 
-## Relacionamentos
-- {Entity A} 1—N {Entity B} via {campo FK}
+## Relationships
+- {Entity A} 1—N {Entity B} via {FK field}
 
-## Campos JSONB / Complexos
-- {campo}: estrutura interna {chaves conhecidas}
+## JSONB / Complex Fields
+- {field}: internal structure {known keys}
 
-## Campos sem uso identificado
-- {campo}: presente no schema mas sem referência na proposta
+## Fields Not Referenced in Proposal
+- {field}: present in schema but no reference in the proposal
 ```
 
-### 1.3 Validar com usuário
+### 1.3 Validate with user
 
 Use `AskUserQuestion`:
 
@@ -167,24 +155,24 @@ Use `AskUserQuestion`:
 {
   "questions": [{
     "header": "Schema OK?",
-    "question": "Encontrei estas entidades e campos no schema. Estão corretos antes de gerar os contratos?",
+    "question": "Found these entities and fields in the schema. Are they correct before generating contracts?",
     "multiSelect": false,
     "options": [
-      { "label": "Confirmar e continuar", "description": "Schema mapeado corretamente" },
-      { "label": "Tenho correções",       "description": "Use Other para descrever o que está errado" }
+      { "label": "Confirm and continue", "description": "Schema mapped correctly" },
+      { "label": "I have corrections",   "description": "Use Other to describe what's wrong" }
     ]
   }]
 }
 ```
 
-- **"Confirmar"** → prosseguir para Checkpoint 2
-- **"Tenho correções" / Other** → aplicar correções no schema-analysis.md e repetir 1.3
+- **"Confirm"** → proceed to Checkpoint 2
+- **"I have corrections" / Other** → apply corrections to schema-analysis.md and repeat 1.3
 
 ---
 
-## CHECKPOINT 2 — Blueprint de Arquitetura (OBRIGATÓRIO antes de gerar contracts)
+## CHECKPOINT 2 — Architecture Blueprint (MANDATORY before generating contracts)
 
-> Use o caminho correspondente ao estilo detectado no PRÉ-VOO.
+> Use the path corresponding to the style detected in PRE-FLIGHT.
 
 ---
 
@@ -196,57 +184,57 @@ Use `AskUserQuestion`:
 npx morph-spec dispatch-agents $ARGUMENTS design
 ```
 
-Use o `taskPrompt` do agente `vsa-architect` do resultado. Chame:
+Use the `taskPrompt` from the `vsa-architect` agent in the result. Call:
 
 ```
-Agent(subagent_type=vsa-architect, prompt=<taskPrompt + conteúdo de proposal.md + schema-analysis.md>)
+Agent(subagent_type=vsa-architect, prompt=<taskPrompt + contents of proposal.md + schema-analysis.md>)
 ```
 
-O agente produz um VSA Blueprint com:
-- Entity fields (baseados no schema validado no Checkpoint 1)
+The agent produces a VSA Blueprint with:
+- Entity fields (based on the schema validated in Checkpoint 1)
 - Operations (GetAll, GetById, Create, Update, Delete + custom)
 - Routes (`GET /api/{feature}s`, `POST /api/{feature}s`, etc.)
 - Error types (`{Entity}Errors.NotFound`, `{Entity}Errors.AlreadyExists`, etc.)
-- Validation rules por campo
+- Validation rules per field
 
-**Paralelize** com outros agentes ativos do dispatch config.
+**Parallelize** with other active agents from the dispatch config.
 
-#### 2-VSA.2 Validar Blueprint com usuário
+#### 2-VSA.2 Validate Blueprint with user
 
-Apresente o blueprint gerado de forma legível e use `AskUserQuestion`:
+Present the generated blueprint in a readable format and use `AskUserQuestion`:
 
 ```json
 {
   "questions": [{
     "header": "Blueprint OK?",
-    "question": "Planejei estes slices e operações para a feature. Confirmar antes de gerar spec e contracts?",
+    "question": "Planned these slices and operations for the feature. Confirm before generating spec and contracts?",
     "multiSelect": false,
     "options": [
-      { "label": "Confirmar blueprint",  "description": "Gerar spec.md e contracts-vsa.cs com este blueprint" },
-      { "label": "Preciso ajustar",      "description": "Use Other para descrever o que mudar no blueprint" }
+      { "label": "Confirm blueprint",  "description": "Generate spec.md and contracts with this blueprint" },
+      { "label": "Need adjustments",   "description": "Use Other to describe what to change" }
     ]
   }]
 }
 ```
 
-- **"Confirmar"** → prosseguir para geração VSA
-- **"Preciso ajustar" / Other** → atualizar blueprint e repetir 2-VSA.2
+- **"Confirm"** → proceed to VSA generation
+- **"Need adjustments" / Other** → update blueprint and repeat 2-VSA.2
 
 ---
 
 ### CHECKPOINT 2-DDD — Domain-Driven Design
 
-#### 2-DDD.1 Determinar Nível de Complexidade
+#### 2-DDD.1 Determine Complexity Level
 
-Leia a proposta e avalie com base nas 5 perguntas de detecção em `framework/standards/architecture/ddd/complexity-levels.md`:
+Read the proposal and evaluate using the 5 detection questions in `framework/standards/architecture/ddd/complexity-levels.md`:
 
-| Nível | Quando usar |
+| Level | When to use |
 |-------|-------------|
-| **Nível 1 (CRUD)** | Entidades simples, sem regras de negócio complexas, CRUD básico |
-| **Nível 2 (Business Logic)** | Invariantes de domínio, workflows de negócio, múltiplas entidades relacionadas |
-| **Nível 3 (Bounded Context)** | Isolamento de contexto, eventos de integração, sistemas distribuídos |
+| **Level 1 (CRUD)** | Simple entities, no complex business rules, basic CRUD |
+| **Level 2 (Business Logic)** | Domain invariants, business workflows, multiple related entities |
+| **Level 3 (Bounded Context)** | Context isolation, integration events, distributed systems |
 
-> Se incerto, assuma Nível 1 e use `AskUserQuestion` para confirmar.
+> If uncertain, assume Level 1 and use `AskUserQuestion` to confirm.
 
 #### 2-DDD.2 Dispatch domain-architect
 
@@ -254,60 +242,60 @@ Leia a proposta e avalie com base nas 5 perguntas de detecção em `framework/st
 npx morph-spec dispatch-agents $ARGUMENTS design
 ```
 
-Use o `taskPrompt` do agente `domain-architect` do resultado. Chame:
+Use the `taskPrompt` from the `domain-architect` agent in the result. Call:
 
 ```
-Agent(subagent_type=domain-architect, prompt=<taskPrompt + conteúdo de proposal.md + schema-analysis.md + nível detectado>)
+Agent(subagent_type=domain-architect, prompt=<taskPrompt + contents of proposal.md + schema-analysis.md + detected level>)
 ```
 
-O agente produz um Architecture Blueprint com:
-- **Nível 1:** Entidades, repositórios, services, DTOs
-- **Nível 2:** AggregateRoot, Value Objects, Domain Events, CQRS handlers
-- **Nível 3:** BC setup, Integration Events, Anti-corruption layer
+The agent produces an Architecture Blueprint with:
+- **Level 1:** Entities, repositories, services, DTOs
+- **Level 2:** AggregateRoot, Value Objects, Domain Events, CQRS handlers
+- **Level 3:** BC setup, Integration Events, Anti-corruption layer
 
-**Paralelize** com outros agentes ativos do dispatch config.
+**Parallelize** with other active agents from the dispatch config.
 
-#### 2-DDD.3 Validar Blueprint com usuário
+#### 2-DDD.3 Validate Blueprint with user
 
-Apresente o blueprint gerado de forma legível e use `AskUserQuestion`:
+Present the generated blueprint in a readable format and use `AskUserQuestion`:
 
 ```json
 {
   "questions": [{
     "header": "Blueprint OK?",
-    "question": "Planejei esta arquitetura de domínio para a feature. Confirmar antes de gerar spec e contracts?",
+    "question": "Planned this domain architecture for the feature. Confirm before generating spec and contracts?",
     "multiSelect": false,
     "options": [
-      { "label": "Confirmar blueprint",  "description": "Gerar spec.md e contracts-level{N}.cs com este blueprint" },
-      { "label": "Preciso ajustar",      "description": "Use Other para descrever o que mudar no blueprint" }
+      { "label": "Confirm blueprint",  "description": "Generate spec.md and contracts with this blueprint" },
+      { "label": "Need adjustments",   "description": "Use Other to describe what to change" }
     ]
   }]
 }
 ```
 
-- **"Confirmar"** → prosseguir para geração DDD
-- **"Preciso ajustar" / Other** → atualizar blueprint e repetir 2-DDD.3
+- **"Confirm"** → proceed to DDD generation
+- **"Need adjustments" / Other** → update blueprint and repeat 2-DDD.3
 
 ---
 
-## Geração de Artefatos
+## Artifact Generation
 
-Com schema validado (Checkpoint 1) e blueprint confirmado (Checkpoint 2):
+With schema validated (Checkpoint 1) and blueprint confirmed (Checkpoint 2):
 
-### Gerar spec.md
+### Generate spec.md
 
-> Estrutura detalhada: `references/spec-authoring-guide.md`
+> Detailed structure: `references/spec-authoring-guide.md`
 
-Crie `.morph/features/$ARGUMENTS/1-design/spec.md` com:
-- Overview, Functional Requirements (FR001...) com critérios de aceitação mensuráveis
+Read the spec-authoring-guide first, then create `.morph/features/$ARGUMENTS/1-design/spec.md` with:
+- Overview, Functional Requirements (FR001...) with measurable acceptance criteria
 - Non-Functional Requirements, Data Model
-- **VSA:** seção `## Architecture Style: Vertical Slice` com slices e operações
-- **DDD:** seção `## Domain Complexity` com nível (1/2/3) e justificativa
-- Infrastructure Requirements (se aplicável)
+- **VSA:** section `## Architecture Style: Vertical Slice` with slices and operations
+- **DDD:** section `## Domain Complexity` with level (1/2/3) and justification
+- Infrastructure Requirements (if applicable)
 
-### Gerar contracts.cs — VSA
+### Generate contracts — VSA
 
-**Fonte obrigatória:** campos do `schema-analysis.md` + operações do VSA Blueprint.
+**Mandatory source:** fields from `schema-analysis.md` + operations from the VSA Blueprint.
 
 ```bash
 npx morph-spec template render \
@@ -321,21 +309,21 @@ npx morph-spec template render \
   }'
 ```
 
-Após renderizar, preencha os `// placeholder:` com os campos reais do schema-analysis.md.
+After rendering, fill in the `// placeholder:` sections with real fields from schema-analysis.md.
 
-**Padrões obrigatórios (VSA):**
-- `sealed` em handlers, endpoints, validators, records
-- `Guid.CreateVersion7()` para IDs
-- `result.Match()` nos endpoints
-- `{Entity}Errors` estático compartilhado por todos os slices
-- CancellationToken em todos os métodos async
+**Mandatory VSA patterns:**
+- `sealed` on handlers, endpoints, validators, records
+- `Guid.CreateVersion7()` for IDs
+- `result.Match()` in endpoints
+- `{Entity}Errors` static shared across all slices
+- CancellationToken in all async methods
 
-### Gerar contracts.cs — DDD
+### Generate contracts — DDD
 
-**Fonte obrigatória:** campos do `schema-analysis.md` + componentes do DDD Blueprint.
+**Mandatory source:** fields from `schema-analysis.md` + components from the DDD Blueprint.
 
 ```bash
-# Substituir {N} pelo nível detectado (1, 2 ou 3):
+# Replace {N} with the detected level (1, 2, or 3):
 npx morph-spec template render \
   dotnet-contracts-level{N} \
   .morph/features/$ARGUMENTS/1-design/contracts.cs \
@@ -346,14 +334,18 @@ npx morph-spec template render \
   }'
 ```
 
-Após renderizar, preencha os `// placeholder:` com os campos reais do schema-analysis.md.
+After rendering, fill in the `// placeholder:` sections with real fields from schema-analysis.md.
+
+**Mandatory DDD patterns:**
+- Level 1: repository interfaces + service with mapped methods
+- Level 2: AggregateRoot with invariants + immutable Value Objects + Domain Events
+- Level 3: adds Integration Events + Bounded Context boundary
+
+### Stack adaptation for contracts
 
-**Padrões obrigatórios (DDD):**
-- Nível 1: interfaces de repositório + service com métodos mapeados
-- Nível 2: AggregateRoot com invariantes + Value Objects imutáveis + Domain Events
-- Nível 3: adiciona Integration Events + Bounded Context boundary
+For TypeScript/Next.js projects, generate `contracts.ts` instead of `contracts.cs`. Use TypeScript interfaces with the same DDD/VSA patterns adapted to the language (e.g., `readonly` fields for Value Objects, union types for status enums, typed event interfaces for Domain Events).
 
-### Gerar decisions.md
+### Generate decisions.md
 
 ```bash
 npx morph-spec template render docs/decisions \
@@ -361,83 +353,83 @@ npx morph-spec template render docs/decisions \
   '{"FEATURE_NAME": "$ARGUMENTS", "DATE": "{{TODAY}}", "decisions": []}'
 ```
 
-ADRs obrigatórios: escolha de arquitetura (VSA vs DDD + justificativa), biblioteca UI (se UI/UX executou), integrações externas, recursos Azure com estimativa de custos.
+Mandatory ADRs: architecture choice (VSA vs DDD + justification), UI library (if UI/UX phase ran), external integrations, Azure resources with cost estimates.
 
 ---
 
-## Sistema de Pontuação de Qualidade
+## Quality Scoring System
 
-Após gerar os artefatos, avalie o design com o **Quality Score (0–100)**:
+After generating artifacts, evaluate the design with the **Quality Score (0–100)**:
 
-| Dimensão | Pts | Critério de máxima pontuação |
-|----------|-----|------------------------------|
-| **Fidelidade ao schema** | 25 | Todos os campos em contracts.cs têm origem rastreável no schema-analysis.md — zero adivinhados |
-| **Cobertura funcional** | 20 | Todos os FRs da proposta estão no spec com critérios de aceitação mensuráveis |
-| **Blueprint completo** | 20 | **VSA:** todos os slices têm handler, validator (exceto GetAll), endpoint e errors \| **DDD:** todas as entidades/aggregates/services têm componentes do nível detectado |
-| **Integrações externas** | 20 | APIs/services com payload, error format e retry policy documentados |
-| **Infra / custos** | 15 | Azure resources estimados com custo, ou "N/A" explícito documentado |
+| Dimension | Pts | Maximum score criteria |
+|-----------|-----|----------------------|
+| **Schema fidelity** | 25 | All fields in contracts have traceable origin in schema-analysis.md — zero guessed |
+| **Functional coverage** | 20 | All FRs from the proposal are in spec with measurable acceptance criteria |
+| **Blueprint complete** | 20 | **VSA:** all slices have handler, validator (except GetAll), endpoint and errors \| **DDD:** all entities/aggregates/services have components for the detected level |
+| **External integrations** | 20 | APIs/services with payload, error format and retry policy documented |
+| **Infra / costs** | 15 | Azure resources estimated with cost, or "N/A" explicitly documented |
 
 **Thresholds:**
 
-| Score | Ação |
-|-------|------|
-| ≥ 85 | Design satisfatório. Oferecer encerrar ou refinar opcionalmente |
-| 70–84 | Continuar. Focar nas dimensões mais fracas |
-| < 70 | Continuar. Questões técnicas abertas bloqueam implementação |
+| Score | Action |
+|-------|--------|
+| ≥ 85 | Design satisfactory. Offer to close or optionally refine |
+| 70–84 | Continue. Focus on the weakest dimensions |
+| < 70 | Continue. Open technical questions block implementation |
 
 ---
 
-## Loop de Qualidade
+## Quality Loop
 
-**Repita até: score ≥ 85 OU usuário aprova.**
+**Repeat until: score ≥ 85 OR user approves.**
 
-### A. Calcular score
+### A. Calculate score
 
-Pontue cada dimensão com base nos artefatos gerados. Identifique as lacunas mais impactantes.
+Score each dimension based on the generated artifacts. Identify the most impactful gaps.
 
-### B. Identificar questões abertas
+### B. Identify open questions
 
-Perguntas típicas por dimensão:
+Typical questions by dimension:
 
-| Dimensão fraca | Exemplos de questões |
-|----------------|----------------------|
-| Schema fidelity | "O campo `metadata` (JSONB) tem estrutura definida? Quais chaves?" |
-| Cobertura funcional | "FR003 diz 'notificar usuário' — por email, push ou ambos?" |
-| Blueprint VSA | "O slice CreateOrder deve disparar um job de email ou é síncrono?" |
-| Blueprint DDD | "O método `Place()` do OrderAggregate deve emitir `OrderPlacedEvent`?" |
-| Integrações | "A API de pagamento usa webhook ou polling para confirmar?" |
-| Infra/custos | "Este feature precisa de storage Azure? Qual tier?" |
+| Weak dimension | Example questions |
+|----------------|-------------------|
+| Schema fidelity | "The `metadata` field (JSONB) — what is its structure? Which keys?" |
+| Functional coverage | "FR003 says 'notify user' — by email, push, or both?" |
+| Blueprint VSA | "Should the CreateOrder slice trigger an email job or is it synchronous?" |
+| Blueprint DDD | "Should `Place()` on OrderAggregate emit `OrderPlacedEvent`?" |
+| Integrations | "Does the payment API use webhook or polling to confirm?" |
+| Infra/costs | "Does this feature need Azure storage? Which tier?" |
 
-### C. Perguntar via AskUserQuestion
+### C. Ask via AskUserQuestion
 
-Máximo 3 questões técnicas por chamada. Na última chamada de cada round, inclua sempre:
+Maximum 3 technical questions per call. In the last call of each round, always include:
 
 ```json
 {
-  "header": "Encerrar?",
-  "question": "Deseja encerrar o design agora ou continuar refinando?",
+  "header": "Continue?",
+  "question": "Continue refining or finalize the design?",
   "multiSelect": false,
   "options": [
-    { "label": "Continuar refinando",   "description": "Claude identificou mais questões abertas" },
-    { "label": "Encerrar design",       "description": "Prosseguir para Clarify com o design atual" }
+    { "label": "Continue refining",   "description": "More open questions identified" },
+    { "label": "Finalize design",     "description": "Proceed to Clarify with current design" }
   ]
 }
 ```
 
-> Se score ≥ 85, ajuste: `"Continuar (opcional)"` com description `"Score {N}/100 — design está satisfatório"`
+> If score ≥ 85, adjust: `"Continue (optional)"` with description `"Score {N}/100 — design is satisfactory"`
 
-### D. Incorporar respostas
+### D. Incorporate answers
 
-Atualize spec.md, contracts.cs e decisions.md com as respostas recebidas. Recalcule o score.
+Update spec.md, contracts, and decisions.md with the answers received. Recalculate the score.
 
-### E. Condição de saída
+### E. Exit condition
 
-- Usuário escolheu **"Encerrar design"** → sair do loop
-- Score ≥ 85 E sem questões novas → sair do loop
+- User chose **"Finalize design"** → exit loop
+- Score ≥ 85 AND no new questions → exit loop
 
 ---
 
-## Pós-Loop: Atualizar State
+## Post-Loop: Update State
 
 ```bash
 npx morph-spec state mark-output $ARGUMENTS schema-analysis
@@ -446,56 +438,56 @@ npx morph-spec state mark-output $ARGUMENTS contracts
 npx morph-spec state mark-output $ARGUMENTS decisions
 ```
 
-Se houver custos Azure estimados:
+If Azure costs were estimated:
 ```bash
 npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
 ```
 
-## PAUSA OBRIGATÓRIA
+## MANDATORY PAUSE
 
 ```json
 {
   "questions": [{
-    "header": "Aprovação",
-    "question": "Design gerado. Aprovar para continuar para Clarify?",
+    "header": "Approval",
+    "question": "Design generated. Approve to continue to Clarify?",
     "multiSelect": false,
     "options": [
-      { "label": "Aprovar e continuar", "description": "Avançar para fase Clarify" },
-      { "label": "Tenho feedback",      "description": "Digite o que deseja mudar (Other)" }
+      { "label": "Approve and continue", "description": "Advance to Clarify phase" },
+      { "label": "I have feedback",      "description": "Describe what to change (Other)" }
     ]
   }]
 }
 ```
 
-- **"Aprovar e continuar"** →
+- **"Approve and continue"** →
   ```bash
   npx morph-spec approve $ARGUMENTS design
   npx morph-spec phase advance $ARGUMENTS
   ```
-- **"Tenho feedback" / Other** → aplicar feedback e repetir PAUSA
+- **"I have feedback" / Other** → apply feedback and repeat PAUSE
 
-## Outputs Gerados
+## Generated Outputs
 
-- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` — Schema real mapeado e validado
-- `.morph/features/$ARGUMENTS/1-design/spec.md` — Especificação técnica completa
-- `.morph/features/$ARGUMENTS/1-design/contracts.cs` — Contracts baseados no schema real (VSA ou DDD)
-- `.morph/features/$ARGUMENTS/1-design/decisions.md` — ADRs documentados
+- `.morph/features/$ARGUMENTS/1-design/schema-analysis.md` — Real schema mapped and validated
+- `.morph/features/$ARGUMENTS/1-design/spec.md` — Complete technical specification
+- `.morph/features/$ARGUMENTS/1-design/contracts.cs` (or `.ts` for TypeScript projects) — Contracts based on real schema (VSA or DDD)
+- `.morph/features/$ARGUMENTS/1-design/decisions.md` — Documented ADRs
 
-## Critérios de Avanço
+## Advancement Criteria
 
-- [x] Estilo de arquitetura detectado em `config.architecture.style`
-- [x] Schema validado pelo usuário (Checkpoint 1)
-- [x] Blueprint confirmado pelo usuário (Checkpoint 2-VSA ou 2-DDD)
-- [x] Score de qualidade ≥ 85 OU usuário encerrou
-- [x] Todos os field names em contracts.cs rastreáveis ao schema-analysis.md
-- [x] State atualizado
-- [x] Usuário aprovou na PAUSA OBRIGATÓRIA
+- [x] Architecture style detected from `config.architecture.style`
+- [x] Schema validated by user (Checkpoint 1)
+- [x] Blueprint confirmed by user (Checkpoint 2-VSA or 2-DDD)
+- [x] Quality score ≥ 85 OR user finalized
+- [x] All field names in contracts traceable to schema-analysis.md
+- [x] State updated
+- [x] User approved at MANDATORY PAUSE
 
 ---
 
 <!-- morph:outputs:design -->
-| Output | Caminho |
-|--------|---------|
+| Output | Path |
+|--------|------|
 | `schemaAnalysis` | `.morph/features/{feature}/1-design/schema-analysis.md` |
 | `spec` | `.morph/features/{feature}/1-design/spec.md` |
 | `contracts` | `.morph/features/{feature}/1-design/contracts.cs` |
@@ -504,4 +496,4 @@ npx morph-spec state set $ARGUMENTS costs.estimated {X.XX}
 | `decisions` | `.morph/features/{feature}/1-design/decisions.md` |
 <!-- /morph:outputs -->
 
-Continuar automaticamente para FASE 3 (Clarify) após aprovação.
+Continue automatically to Phase 3 (Clarify) after approval.