feat(writer): 🎉 Enhance script execution order and add symlink skipping

* Update script execution to sort by Priority, Sequence, and Name.
* Add functionality to skip symbolic links during directory scanning.
* Improve documentation to reflect changes in execution order and features.
* Add tests for symlink skipping and ensure correct script sorting.

pkg/readers/sqldir/reader_test.go

@@ -373,3 +373,65 @@ func TestReader_MixedFormat(t *testing.T) {
 		}
 	}
 }
+
+func TestReader_SkipSymlinks(t *testing.T) {
+	// Create temporary test directory
+	tempDir, err := os.MkdirTemp("", "sqldir-test-symlink-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	// Create a real SQL file
+	realFile := filepath.Join(tempDir, "1_001_real_file.sql")
+	if err := os.WriteFile(realFile, []byte("SELECT 1;"), 0644); err != nil {
+		t.Fatalf("Failed to create real file: %v", err)
+	}
+
+	// Create another file to link to
+	targetFile := filepath.Join(tempDir, "2_001_target.sql")
+	if err := os.WriteFile(targetFile, []byte("SELECT 2;"), 0644); err != nil {
+		t.Fatalf("Failed to create target file: %v", err)
+	}
+
+	// Create a symlink to the target file (this should be skipped)
+	symlinkFile := filepath.Join(tempDir, "3_001_symlink.sql")
+	if err := os.Symlink(targetFile, symlinkFile); err != nil {
+		// Skip test on systems that don't support symlinks (e.g., Windows without admin)
+		t.Skipf("Symlink creation not supported: %v", err)
+	}
+
+	// Create reader
+	reader := NewReader(&readers.ReaderOptions{
+		FilePath: tempDir,
+	})
+
+	// Read database
+	db, err := reader.ReadDatabase()
+	if err != nil {
+		t.Fatalf("ReadDatabase failed: %v", err)
+	}
+
+	schema := db.Schemas[0]
+
+	// Should only have 2 scripts (real_file and target), symlink should be skipped
+	if len(schema.Scripts) != 2 {
+		t.Errorf("Expected 2 scripts (symlink should be skipped), got %d", len(schema.Scripts))
+	}
+
+	// Verify the scripts are the real files, not the symlink
+	scriptNames := make(map[string]bool)
+	for _, script := range schema.Scripts {
+		scriptNames[script.Name] = true
+	}
+
+	if !scriptNames["real_file"] {
+		t.Error("Expected 'real_file' script to be present")
+	}
+	if !scriptNames["target"] {
+		t.Error("Expected 'target' script to be present")
+	}
+	if scriptNames["symlink"] {
+		t.Error("Symlink script should have been skipped but was found")
+	}
+}