@polymorphism-tech/morph-spec 4.10.7 → 4.10.8

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

@@ -1,270 +1,270 @@
----
-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, AskUserQuestion
-cliVersion: "4.10.7"
----
-
-# MORPH Codebase Analysis - Design Sub-phase
-
-> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
-> Called by `phase-design.md` Step 2. Not a standalone user command.
-
-Automates existing code analysis to generate `schema-analysis.md` with real database/code data.
-
-## Prerequisites
-
-- [ ] Phase 1 (Setup) completed
-- [ ] Feature has approved `proposal.md`
-- [ ] Project context loaded (stack, agents)
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
-
-| Action | Tool | Alternative |
-|------|------------|-------------|
-| List database tables | **Supabase MCP** `list_tables()` | **Grep** `.from(` in code |
-| Get table schema | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
-| Get FK relationships | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
-| Get RLS policies | **Supabase MCP** `query()` | **Read** policy files |
-| Find queries in code | **Grep** `\.from\(` in `*.ts,*.tsx,*.js,*.cs` | — |
-| Find type definitions | **Glob** `src/**/types/**/*.ts` or `**/Entities/**/*.cs` | — |
-| Read found files | **Read** each file | — |
-| Complex multi-file analysis | **Task** (subagent Explore) | Read individual |
-| Generate schema-analysis.md | **Write** using template | **Bash** template render |
-
-**MCPs for this phase:** Supabase (schema — **PRIORITY**), Generic database MCPs.
-
----
-
-## Automated Workflow
-
-### Step 1: Detect Analysis Method
-
-**IMPORTANT:** Do not assume the MCP is available and accessible.
-Verify first with a test call before attempting to use it.
-
-```
-1. IF Supabase MCP configured in settings.json:
-   → Try mcp__supabase__list_tables() with implicit timeout
-   → IF returns valid data (array of tables with content):
-      → Use Method A (direct MCP)
-   → IF returns error, timeout, empty array, or inaccessible data:
-      → Log: "Supabase MCP configured but inaccessible (CloudSQL? Auth? Permissions?)"
-      → Use Method B (static code analysis)
-
-2. IF Database MCP (other) configured:
-   → Test connectivity with trivial query before using
-   → IF OK: Use adapted Method A
-   → IF fails: Use Method B
-
-3. IF no MCP available:
-   → Use Method B (static code analysis)
-```
-
-**Signs of inaccessible MCP:**
-- Empty response or `[]` from `list_tables()`
-- Authentication error / permission denied
-- Returned schema doesn't match code (e.g., tables exist in code but not in MCP)
-- Project uses database other than Supabase (CloudSQL, RDS, Azure SQL, etc.)
-
-### Step 2A: MCP Method (Preferred)
-
-**Tools:** Supabase MCP
-
-```javascript
-// 1. List all tables
-const tables = await mcp__supabase__list_tables();
-
-// 2. For each feature-relevant table:
-for (const table of relevantTables) {
-  // 2a. Complete schema
-  const schema = await mcp__supabase__get_table_schema({ table: table.name });
-  // → column_name, data_type, is_nullable, column_default
-
-  // 2b. Relationships
-  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 (security)
-  const policies = await mcp__supabase__query({
-    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
-  });
-}
-```
-
-### Step 2B: Static Analysis Method (Fallback)
-
-**Tools:** Grep, Glob, Read, Task (subagent for large projects)
-
-**Phase B1: Find Queries**
-
-```
-Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
-Type: ts,tsx,js,jsx,cs
-Output: files_with_matches
-```
-
-**Phase B2: Read Query Files**
-
-For each found file, use **Read** to extract:
-- Table names: `from('leads')`, `DbSet<Lead>`, `FROM leads`
-- Column names: `.select('fullname, phonenumber')`, `l.FullName`
-- Data types: TypeScript interfaces, C# DTOs
-- Relationships: JOIN clauses, navigation properties
-
-**Phase B3: Find 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"
-```
-
-**Phase B4: When to use Task (subagent)**
-
-Use Task subagent **ONLY** when:
-- Project has 20+ query files
-- Multiple data access patterns (Supabase + EF Core + raw SQL)
-- Precise cross-context analysis across many files
-
-Do not use Task subagent when:
-- Project has < 10 query files (direct Read is faster)
-- Data access pattern is uniform (only Supabase OR only EF Core)
-
-### Step 2B-Format: Standardized Format for Static Analysis
-
-**IMPORTANT:** When using Method B (static analysis), **always use the official template**.
-This ensures `contracts.cs` can be generated mechanically, without manual interpretation.
-
-The template is at `framework/templates/docs/schema-analysis.md`. Use it 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" }
-        ]
-      }
-    ]
-  }'
-```
-
-**If template render is not available**, use **Write** tool to create the file directly
-following the structure above. The table and mismatch format is MANDATORY — without standard format
-it's not possible to generate contracts.cs mechanically.
-
-### Step 3: Map Inconsistencies
-
-Create a map of:
-
-| Frontend/Code | Database | Type | Problem |
-|----------------|----------------|------|----------|
-| user.name | users.fullname | string | MISMATCH |
-| lead.phone | leads.phonenumber | string | MISMATCH |
-| order.metadata | orders.metadata | JSONB | Type complex |
-
-### Step 4: Generate `schema-analysis.md`
-
-Use the template at `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": "..." }'
-```
-
-OR use **Write** tool to create directly with collected data.
-
-### Step 5: Update State
-
-```bash
-npx morph-spec state mark-output {feature-name} schema-analysis
-```
-
----
-
-## Outputs
-
-- `.morph/features/{feature}/1-design/schema-analysis.md`
-- State updated with `schemaAnalysis` output
-
-## CHECKPOINT
-
-Before proceeding to contracts.cs, present results and ask for confirmation using `AskUserQuestion`:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Schema Review",
-      "question": "Schema analysis complete: {N} tables, {N} field mismatches, {N} type mismatches, {N} relationships. Is the analysis correct?",
-      "multiSelect": false,
-      "options": [
-        { "label": "Correct", "description": "Schema analysis matches the real database" },
-        { "label": "Has issues", "description": "I see problems — let me explain" }
-      ]
-    },
-    {
-      "header": "Contracts",
-      "question": "May I generate contracts.cs based on this real schema?",
-      "multiSelect": false,
-      "options": [
-        { "label": "Generate contracts", "description": "Proceed to contracts.cs using the analyzed schema" },
-        { "label": "Wait", "description": "I want to review schema-analysis.md first" }
-      ]
-    }
-  ]
-}
-```
-
-**If "Has issues"** → ask what's wrong, fix schema-analysis.md, re-present checkpoint.
-**If "Correct" + "Generate contracts"** → proceed to contracts generation.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+---
+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, AskUserQuestion
+cliVersion: "4.10.8"
+---
+
+# MORPH Codebase Analysis - Design Sub-phase
+
+> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
+> Called by `phase-design.md` Step 2. Not a standalone user command.
+
+Automates existing code analysis to generate `schema-analysis.md` with real database/code data.
+
+## Prerequisites
+
+- [ ] Phase 1 (Setup) completed
+- [ ] Feature has approved `proposal.md`
+- [ ] Project context loaded (stack, agents)
+
+## Recommended Tools
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
+
+| Action | Tool | Alternative |
+|------|------------|-------------|
+| List database tables | **Supabase MCP** `list_tables()` | **Grep** `.from(` in code |
+| Get table schema | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
+| Get FK relationships | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
+| Get RLS policies | **Supabase MCP** `query()` | **Read** policy files |
+| Find queries in code | **Grep** `\.from\(` in `*.ts,*.tsx,*.js,*.cs` | — |
+| Find type definitions | **Glob** `src/**/types/**/*.ts` or `**/Entities/**/*.cs` | — |
+| Read found files | **Read** each file | — |
+| Complex multi-file analysis | **Task** (subagent Explore) | Read individual |
+| Generate schema-analysis.md | **Write** using template | **Bash** template render |
+
+**MCPs for this phase:** Supabase (schema — **PRIORITY**), Generic database MCPs.
+
+---
+
+## Automated Workflow
+
+### Step 1: Detect Analysis Method
+
+**IMPORTANT:** Do not assume the MCP is available and accessible.
+Verify first with a test call before attempting to use it.
+
+```
+1. IF Supabase MCP configured in settings.json:
+   → Try mcp__supabase__list_tables() with implicit timeout
+   → IF returns valid data (array of tables with content):
+      → Use Method A (direct MCP)
+   → IF returns error, timeout, empty array, or inaccessible data:
+      → Log: "Supabase MCP configured but inaccessible (CloudSQL? Auth? Permissions?)"
+      → Use Method B (static code analysis)
+
+2. IF Database MCP (other) configured:
+   → Test connectivity with trivial query before using
+   → IF OK: Use adapted Method A
+   → IF fails: Use Method B
+
+3. IF no MCP available:
+   → Use Method B (static code analysis)
+```
+
+**Signs of inaccessible MCP:**
+- Empty response or `[]` from `list_tables()`
+- Authentication error / permission denied
+- Returned schema doesn't match code (e.g., tables exist in code but not in MCP)
+- Project uses database other than Supabase (CloudSQL, RDS, Azure SQL, etc.)
+
+### Step 2A: MCP Method (Preferred)
+
+**Tools:** Supabase MCP
+
+```javascript
+// 1. List all tables
+const tables = await mcp__supabase__list_tables();
+
+// 2. For each feature-relevant table:
+for (const table of relevantTables) {
+  // 2a. Complete schema
+  const schema = await mcp__supabase__get_table_schema({ table: table.name });
+  // → column_name, data_type, is_nullable, column_default
+
+  // 2b. Relationships
+  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 (security)
+  const policies = await mcp__supabase__query({
+    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
+  });
+}
+```
+
+### Step 2B: Static Analysis Method (Fallback)
+
+**Tools:** Grep, Glob, Read, Task (subagent for large projects)
+
+**Phase B1: Find Queries**
+
+```
+Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
+Type: ts,tsx,js,jsx,cs
+Output: files_with_matches
+```
+
+**Phase B2: Read Query Files**
+
+For each found file, use **Read** to extract:
+- Table names: `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- Column names: `.select('fullname, phonenumber')`, `l.FullName`
+- Data types: TypeScript interfaces, C# DTOs
+- Relationships: JOIN clauses, navigation properties
+
+**Phase B3: Find 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"
+```
+
+**Phase B4: When to use Task (subagent)**
+
+Use Task subagent **ONLY** when:
+- Project has 20+ query files
+- Multiple data access patterns (Supabase + EF Core + raw SQL)
+- Precise cross-context analysis across many files
+
+Do not use Task subagent when:
+- Project has < 10 query files (direct Read is faster)
+- Data access pattern is uniform (only Supabase OR only EF Core)
+
+### Step 2B-Format: Standardized Format for Static Analysis
+
+**IMPORTANT:** When using Method B (static analysis), **always use the official template**.
+This ensures `contracts.cs` can be generated mechanically, without manual interpretation.
+
+The template is at `framework/templates/docs/schema-analysis.md`. Use it 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" }
+        ]
+      }
+    ]
+  }'
+```
+
+**If template render is not available**, use **Write** tool to create the file directly
+following the structure above. The table and mismatch format is MANDATORY — without standard format
+it's not possible to generate contracts.cs mechanically.
+
+### Step 3: Map Inconsistencies
+
+Create a map of:
+
+| Frontend/Code | Database | Type | Problem |
+|----------------|----------------|------|----------|
+| user.name | users.fullname | string | MISMATCH |
+| lead.phone | leads.phonenumber | string | MISMATCH |
+| order.metadata | orders.metadata | JSONB | Type complex |
+
+### Step 4: Generate `schema-analysis.md`
+
+Use the template at `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": "..." }'
+```
+
+OR use **Write** tool to create directly with collected data.
+
+### Step 5: Update State
+
+```bash
+npx morph-spec state mark-output {feature-name} schema-analysis
+```
+
+---
+
+## Outputs
+
+- `.morph/features/{feature}/1-design/schema-analysis.md`
+- State updated with `schemaAnalysis` output
+
+## CHECKPOINT
+
+Before proceeding to contracts.cs, present results and ask for confirmation using `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Schema Review",
+      "question": "Schema analysis complete: {N} tables, {N} field mismatches, {N} type mismatches, {N} relationships. Is the analysis correct?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Correct", "description": "Schema analysis matches the real database" },
+        { "label": "Has issues", "description": "I see problems — let me explain" }
+      ]
+    },
+    {
+      "header": "Contracts",
+      "question": "May I generate contracts.cs based on this real schema?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Generate contracts", "description": "Proceed to contracts.cs using the analyzed schema" },
+        { "label": "Wait", "description": "I want to review schema-analysis.md first" }
+      ]
+    }
+  ]
+}
+```
+
+**If "Has issues"** → ask what's wrong, fix schema-analysis.md, re-present checkpoint.
+**If "Correct" + "Generate contracts"** → proceed to contracts generation.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*