@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

package/framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md

@@ -1,252 +1,252 @@
----
-name: 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"
----
-
-# MORPH Codebase Analysis - Sub-fase de DESIGN
-
-> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
-> Called by `phase-design.md` Passo 2. Not a standalone user command.
-
-Automatiza a análise de código existente para gerar `schema-analysis.md` com dados reais do banco/código.
-
-## Pré-requisitos
-
-- [ ] FASE 1 (Setup) concluída
-- [ ] Feature tem `proposal.md` aprovado
-- [ ] Contexto do projeto carregado (stack, agentes)
-
-## Ferramentas Recomendadas
-
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Listar tabelas do banco | **Supabase MCP** `list_tables()` | **Grep** `.from(` no código |
-| Obter schema de tabela | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
-| Obter relacionamentos FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
-| Obter políticas RLS | **Supabase MCP** `query()` | **Read** policy files |
-| Encontrar queries no código | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
-| Encontrar type definitions | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
-| Ler arquivos encontrados | **Read** cada arquivo | — |
-| Análise multi-arquivo complexa | **Task** (subagent Explore) | Read individual |
-| Gerar schema-analysis.md | **Write** usando template | **Bash** template render |
-
-**MCPs desta fase:** Supabase (schema — **PRIORITÁRIO**), Database MCPs genéricos.
-
----
-
-## Workflow Automatizado
-
-### Passo 1: Detectar Método de Análise
-
-**IMPORTANTE (Problem 8 fix):** Não assuma que o MCP está disponível e acessível.
-Verifique primeiro com uma chamada de teste antes de tentar usá-lo.
-
-```
-1. SE MCP Supabase configurado no settings.json:
-   → Tentar mcp__supabase__list_tables() com timeout implícito
-   → SE retornar dados válidos (array de tabelas com conteúdo):
-      → Usar Método A (MCP direto)
-   → SE retornar erro, timeout, array vazio, ou dados inacessíveis:
-      → Logar: "MCP Supabase configurado mas inacessível (CloudSQL? Auth? Permissões?)"
-      → Usar Método B (análise estática de código)
-
-2. SE MCP Database (outro) configurado:
-   → Testar conectividade com query trivial antes de usar
-   → SE OK: Usar Método A adaptado
-   → SE falhar: Usar Método B
-
-3. SE nenhum MCP disponível:
-   → Usar Método B (análise estática de código)
-```
-
-**Sinais de MCP inacessível:**
-- Resposta vazia ou `[]` em `list_tables()`
-- Erro de autenticação / permissão negada
-- Schema retornado não bate com o código (ex: tabelas existem no código mas não no MCP)
-- Projeto usa banco diferente do Supabase (CloudSQL, RDS, Azure SQL, etc.)
-
-### Passo 2A: Método MCP (Preferencial)
-
-**Ferramentas:** Supabase MCP
-
-```javascript
-// 1. Listar todas as tabelas
-const tables = await mcp__supabase__list_tables();
-
-// 2. Para cada tabela relevante à feature:
-for (const table of relevantTables) {
-  // 2a. Schema completo
-  const schema = await mcp__supabase__get_table_schema({ table: table.name });
-  // → column_name, data_type, is_nullable, column_default
-
-  // 2b. Relacionamentos
-  const rels = await mcp__supabase__get_relationships({ table: table.name });
-  // → foreign_table, foreign_column, constraint_type
-
-  // 2c. Indexes
-  const indexes = await mcp__supabase__query({
-    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
-  });
-
-  // 2d. RLS policies (segurança)
-  const policies = await mcp__supabase__query({
-    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
-  });
-}
-```
-
-### Passo 2B: Método Análise Estática (Fallback)
-
-**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
-
-**Fase B1: Encontrar Queries**
-
-```
-Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
-Type: ts,tsx,js,jsx,cs
-Output: files_with_matches
-```
-
-**Fase B2: Ler Arquivos de Query**
-
-Para cada arquivo encontrado, use **Read** para extrair:
-- Nomes de tabelas: `from('leads')`, `DbSet<Lead>`, `FROM leads`
-- Nomes de colunas: `.select('fullname, phonenumber')`, `l.FullName`
-- Tipos de dados: TypeScript interfaces, C# DTOs
-- Relacionamentos: JOIN clauses, navigation properties
-
-**Fase B3: Encontrar Type Definitions**
-
-```
-# TypeScript/JavaScript:
-Glob: "src/**/types/**/*.ts"
-Glob: "src/**/*.d.ts"
-Glob: "src/**/interfaces/*.ts"
-
-# .NET:
-Glob: "**/*Dto.cs"
-Glob: "**/Entities/**/*.cs"
-Glob: "**/Models/**/*.cs"
-```
-
-**Fase B4: Quando usar Task (subagent)**
-
-Use Task subagent **APENAS** quando:
-- Projeto tem 20+ arquivos de query
-- Múltiplos padrões de acesso a dados (Supabase + EF Core + raw SQL)
-- Análise precisa de contexto cruzado entre muitos arquivos
-
-Não use Task subagent quando:
-- Projeto tem < 10 arquivos de query (Read direto é mais rápido)
-- Padrão de acesso a dados é uniforme (só Supabase OU só EF Core)
-
-### Passo 2B-Formato: Formato Padronizado para Análise Estática
-
-**IMPORTANTE (Problem 10 fix):** Quando usar Método B (análise estática), **sempre use o template oficial**.
-Isso garante que `contracts.cs` pode ser gerado mecanicamente, sem interpretação manual.
-
-O template está em `framework/templates/docs/schema-analysis.md`. Use-o via:
-
-```bash
-npx morph-spec template render docs/schema-analysis \
-  .morph/features/{feature}/1-design/schema-analysis.md \
-  '{
-    "FEATURE_NAME": "{feature}",
-    "FEATURE_NAME_TITLE": "{Feature Display Name}",
-    "DATE": "YYYY-MM-DD",
-    "AUTHOR": "Claude Code (Sonnet 4.6)",
-    "method": "Static Code Analysis",
-    "mcpUsed": "No",
-    "tableCount": N,
-    "fileCount": N,
-    "tables": [
-      {
-        "name": "table_name",
-        "codeSource": "path/to/file.ts",
-        "columns": [
-          { "name": "column_name", "type": "string", "nullable": false, "notes": "from SELECT query" }
-        ],
-        "relationships": [{ "description": "belongs to users via user_id" }],
-        "indexes": [{ "description": "idx_leads_created_at (created_at DESC)" }]
-      }
-    ],
-    "fieldMismatches": [
-      { "description": "Code uses user.name but DB column is users.fullname" }
-    ],
-    "typeMismatches": [],
-    "relationshipIssues": [],
-    "dtoRecommendations": [
-      {
-        "tableName": "leads",
-        "dtoName": "LeadDto",
-        "fields": [
-          { "type": "Guid", "name": "Id", "nullable": false, "comment": "PK" },
-          { "type": "string", "name": "FullName", "nullable": false, "comment": "leads.fullname" }
-        ]
-      }
-    ]
-  }'
-```
-
-**Se o template render não estiver disponível**, use **Write** tool para criar o arquivo diretamente
-seguindo a estrutura acima. O formato das tabelas e mismatches é OBRIGATÓRIO — sem formato padrão
-não é possível gerar contracts.cs mecanicamente.
-
-### Passo 3: Mapear Inconsistências
-
-Crie um mapa de:
-
-| Frontend/Código | Banco de Dados | Tipo | Problema |
-|----------------|----------------|------|----------|
-| user.name | users.fullname | string | ❌ MISMATCH |
-| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
-| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
-
-### Passo 4: Gerar `schema-analysis.md`
-
-Use o template em `framework/templates/docs/schema-analysis.md`:
-
-```bash
-npx morph-spec template render docs/schema-analysis \
-  .morph/features/{feature-name}/1-design/schema-analysis.md \
-  '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
-```
-
-OU use **Write** tool para criar diretamente com os dados coletados.
-
-### Passo 5: Atualizar State
-
-```bash
-npx morph-spec state mark-output {feature-name} schema-analysis
-```
-
----
-
-## Outputs
-
-- `.morph/features/{feature}/1-design/schema-analysis.md`
-- State atualizado com output `schemaAnalysis`
-
-## CHECKPOINT
-
-Antes de prosseguir para contracts.cs, apresente ao usuário:
-
-- [ ] Analisei {N} tabelas
-- [ ] Encontrei {N} field name mismatches
-- [ ] Encontrei {N} type mismatches
-- [ ] Mapeei {N} relacionamentos
-- [ ] `schema-analysis.md` criado
-
-**Perguntas obrigatórias:**
-1. "O schema analysis está correto?"
-2. "Posso gerar contracts.cs com base nesse schema real?"
-
----
-
+---
+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.9.0"
+---
+
+# MORPH Codebase Analysis - Sub-fase de DESIGN
+
+> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
+> Called by `phase-design.md` Passo 2. Not a standalone user command.
+
+Automatiza a análise de código existente para gerar `schema-analysis.md` com dados reais do banco/código.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] Feature tem `proposal.md` aprovado
+- [ ] Contexto do projeto carregado (stack, agentes)
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Listar tabelas do banco | **Supabase MCP** `list_tables()` | **Grep** `.from(` no código |
+| Obter schema de tabela | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
+| Obter relacionamentos FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
+| Obter políticas RLS | **Supabase MCP** `query()` | **Read** policy files |
+| Encontrar queries no código | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
+| Encontrar type definitions | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
+| Ler arquivos encontrados | **Read** cada arquivo | — |
+| Análise multi-arquivo complexa | **Task** (subagent Explore) | Read individual |
+| Gerar schema-analysis.md | **Write** usando template | **Bash** template render |
+
+**MCPs desta fase:** Supabase (schema — **PRIORITÁRIO**), Database MCPs genéricos.
+
+---
+
+## Workflow Automatizado
+
+### Passo 1: Detectar Método de Análise
+
+**IMPORTANTE (Problem 8 fix):** Não assuma que o MCP está disponível e acessível.
+Verifique primeiro com uma chamada de teste antes de tentar usá-lo.
+
+```
+1. SE MCP Supabase configurado no settings.json:
+   → Tentar mcp__supabase__list_tables() com timeout implícito
+   → SE retornar dados válidos (array de tabelas com conteúdo):
+      → Usar Método A (MCP direto)
+   → SE retornar erro, timeout, array vazio, ou dados inacessíveis:
+      → Logar: "MCP Supabase configurado mas inacessível (CloudSQL? Auth? Permissões?)"
+      → Usar Método B (análise estática de código)
+
+2. SE MCP Database (outro) configurado:
+   → Testar conectividade com query trivial antes de usar
+   → SE OK: Usar Método A adaptado
+   → SE falhar: Usar Método B
+
+3. SE nenhum MCP disponível:
+   → Usar Método B (análise estática de código)
+```
+
+**Sinais de MCP inacessível:**
+- Resposta vazia ou `[]` em `list_tables()`
+- Erro de autenticação / permissão negada
+- Schema retornado não bate com o código (ex: tabelas existem no código mas não no MCP)
+- Projeto usa banco diferente do Supabase (CloudSQL, RDS, Azure SQL, etc.)
+
+### Passo 2A: Método MCP (Preferencial)
+
+**Ferramentas:** Supabase MCP
+
+```javascript
+// 1. Listar todas as tabelas
+const tables = await mcp__supabase__list_tables();
+
+// 2. Para cada tabela relevante à feature:
+for (const table of relevantTables) {
+  // 2a. Schema completo
+  const schema = await mcp__supabase__get_table_schema({ table: table.name });
+  // → column_name, data_type, is_nullable, column_default
+
+  // 2b. Relacionamentos
+  const rels = await mcp__supabase__get_relationships({ table: table.name });
+  // → foreign_table, foreign_column, constraint_type
+
+  // 2c. Indexes
+  const indexes = await mcp__supabase__query({
+    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
+  });
+
+  // 2d. RLS policies (segurança)
+  const policies = await mcp__supabase__query({
+    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
+  });
+}
+```
+
+### Passo 2B: Método Análise Estática (Fallback)
+
+**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
+
+**Fase B1: Encontrar Queries**
+
+```
+Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
+Type: ts,tsx,js,jsx,cs
+Output: files_with_matches
+```
+
+**Fase B2: Ler Arquivos de Query**
+
+Para cada arquivo encontrado, use **Read** para extrair:
+- Nomes de tabelas: `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- Nomes de colunas: `.select('fullname, phonenumber')`, `l.FullName`
+- Tipos de dados: TypeScript interfaces, C# DTOs
+- Relacionamentos: JOIN clauses, navigation properties
+
+**Fase B3: Encontrar Type Definitions**
+
+```
+# TypeScript/JavaScript:
+Glob: "src/**/types/**/*.ts"
+Glob: "src/**/*.d.ts"
+Glob: "src/**/interfaces/*.ts"
+
+# .NET:
+Glob: "**/*Dto.cs"
+Glob: "**/Entities/**/*.cs"
+Glob: "**/Models/**/*.cs"
+```
+
+**Fase B4: Quando usar Task (subagent)**
+
+Use Task subagent **APENAS** quando:
+- Projeto tem 20+ arquivos de query
+- Múltiplos padrões de acesso a dados (Supabase + EF Core + raw SQL)
+- Análise precisa de contexto cruzado entre muitos arquivos
+
+Não use Task subagent quando:
+- Projeto tem < 10 arquivos de query (Read direto é mais rápido)
+- Padrão de acesso a dados é uniforme (só Supabase OU só EF Core)
+
+### Passo 2B-Formato: Formato Padronizado para Análise Estática
+
+**IMPORTANTE (Problem 10 fix):** Quando usar Método B (análise estática), **sempre use o template oficial**.
+Isso garante que `contracts.cs` pode ser gerado mecanicamente, sem interpretação manual.
+
+O template está em `framework/templates/docs/schema-analysis.md`. Use-o via:
+
+```bash
+npx morph-spec template render docs/schema-analysis \
+  .morph/features/{feature}/1-design/schema-analysis.md \
+  '{
+    "FEATURE_NAME": "{feature}",
+    "FEATURE_NAME_TITLE": "{Feature Display Name}",
+    "DATE": "YYYY-MM-DD",
+    "AUTHOR": "Claude Code (Sonnet 4.6)",
+    "method": "Static Code Analysis",
+    "mcpUsed": "No",
+    "tableCount": N,
+    "fileCount": N,
+    "tables": [
+      {
+        "name": "table_name",
+        "codeSource": "path/to/file.ts",
+        "columns": [
+          { "name": "column_name", "type": "string", "nullable": false, "notes": "from SELECT query" }
+        ],
+        "relationships": [{ "description": "belongs to users via user_id" }],
+        "indexes": [{ "description": "idx_leads_created_at (created_at DESC)" }]
+      }
+    ],
+    "fieldMismatches": [
+      { "description": "Code uses user.name but DB column is users.fullname" }
+    ],
+    "typeMismatches": [],
+    "relationshipIssues": [],
+    "dtoRecommendations": [
+      {
+        "tableName": "leads",
+        "dtoName": "LeadDto",
+        "fields": [
+          { "type": "Guid", "name": "Id", "nullable": false, "comment": "PK" },
+          { "type": "string", "name": "FullName", "nullable": false, "comment": "leads.fullname" }
+        ]
+      }
+    ]
+  }'
+```
+
+**Se o template render não estiver disponível**, use **Write** tool para criar o arquivo diretamente
+seguindo a estrutura acima. O formato das tabelas e mismatches é OBRIGATÓRIO — sem formato padrão
+não é possível gerar contracts.cs mecanicamente.
+
+### Passo 3: Mapear Inconsistências
+
+Crie um mapa de:
+
+| Frontend/Código | Banco de Dados | Tipo | Problema |
+|----------------|----------------|------|----------|
+| user.name | users.fullname | string | ❌ MISMATCH |
+| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
+| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
+
+### Passo 4: Gerar `schema-analysis.md`
+
+Use o template em `framework/templates/docs/schema-analysis.md`:
+
+```bash
+npx morph-spec template render docs/schema-analysis \
+  .morph/features/{feature-name}/1-design/schema-analysis.md \
+  '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
+```
+
+OU use **Write** tool para criar diretamente com os dados coletados.
+
+### Passo 5: Atualizar State
+
+```bash
+npx morph-spec state mark-output {feature-name} schema-analysis
+```
+
+---
+
+## Outputs
+
+- `.morph/features/{feature}/1-design/schema-analysis.md`
+- State atualizado com output `schemaAnalysis`
+
+## CHECKPOINT
+
+Antes de prosseguir para contracts.cs, apresente ao usuário:
+
+- [ ] Analisei {N} tabelas
+- [ ] Encontrei {N} field name mismatches
+- [ ] Encontrei {N} type mismatches
+- [ ] Mapeei {N} relacionamentos
+- [ ] `schema-analysis.md` criado
+
+**Perguntas obrigatórias:**
+1. "O schema analysis está correto?"
+2. "Posso gerar contracts.cs com base nesse schema real?"
+
+---
+
 *MORPH-SPEC by Polymorphism Tech*