docs: updated order

Author: dieppa

.claude/settings.local.json

@@ -13,7 +13,10 @@
       "Bash(yarn start)",
       "Bash(PORT=3001 yarn start)",
       "Bash(sed:*)",
-      "Bash(npm run build:*)"
+      "Bash(npm run build:*)",
+      "Bash(yarn build)",
+      "Read(//Users/dieppa/workspace/flamingock/**)",
+      "Bash(./gradlew:*)"
     ],
     "deny": []
   }

CLAUDE.md

@@ -190,7 +190,7 @@ Flamingock works with two types of target systems:
 #### Transactional Target Systems
 - **Examples**: PostgreSQL, MySQL, MongoDB (4.0+), Oracle
 - **Native Capabilities**: Built-in rollback, atomicity, consistency guarantees
-- **In Flamingock**: Changes can leverage native transactions via `@ChangeUnit(transactional = true)`
+- **In Flamingock**: Changes can leverage native transactions via `@Change(transactional = true)`
 - **Rollback Strategy**: Automatic (database handles it) or manual via `@RollbackExecution`
 
 #### Non-Transactional Target Systems

FLAMINGOCK_RECOVERY_SAFETY_KNOWLEDGE.md

@@ -65,7 +65,7 @@ Before diving into recovery strategies, it's essential to understand Flamingock'
 
 ```java
 @TargetSystem("user-database")  // This is the TARGET - where business changes go
-@ChangeUnit(id = "user-migration", order = "001", author = "team-data")
+@Change(id = "user-migration", order = "20250207_01", author = "team-data")
 public class UserMigration {
 
     @Execution
@@ -115,7 +115,7 @@ Flamingock works with two types of target systems based on their native transact
 **Underlying Technology**: Systems that natively support ACID transactions
 - **Examples**: PostgreSQL, MySQL, MongoDB (4.0+), Oracle
 - **Native Capabilities**: Built-in rollback, atomicity, consistency guarantees
-- **In Flamingock**: Changes can leverage native transactions via `@ChangeUnit(transactional = true)`
+- **In Flamingock**: Changes can leverage native transactions via `@Change(transactional = true)`
 - **Rollback Strategy**: Automatic (database handles it) or manual via `@RollbackExecution` when the change itself it's not transactional, despite being a transactional target system(like DDL operations in MySQL,a s we mentioned)
 
 #### Non-Transactional Target Systems  
@@ -140,7 +140,7 @@ Even when targeting a transactional system, a change can be non-transactional.
 
 ```java
 // Transactional change - relies on database rollback
-@ChangeUnit(id = "user-migration", order = "001", transactional = true, author = "team")
+@Change(id = "user-migration", order = "20250207_01", transactional = true, author = "team")
 @TargetSystem("user-db")
 public class UserMigration {
 
@@ -160,7 +160,7 @@ public class UserMigration {
 
 // Non-transactional change - requires explicit rollback
 @TargetSystem("user-db") 
-@ChangeUnit(id = "schema-changes", order = "002", transactional = false, author = "dba-team")
+@Change(id = "schema-changes", order = "20250207_02", transactional = false, author = "dba-team")
 public class SchemaChanges {
 
     @Execution  
@@ -218,7 +218,7 @@ Flamingock provides two recovery strategies that users can choose:
 **Example Configuration**:
 ```java
 @TargetSystem("user-database")
-@ChangeUnit(id = "critical-user-migration", order = "001", author = "team-data")
+@Change(id = "critical-user-migration", order = "20250207_01", author = "team-data")
 // No @Recovery annotation needed - MANUAL_INTERVENTION is default
 public class CriticalUserMigration {
 
@@ -274,7 +274,7 @@ public class CriticalUserMigration {
 **Example Configuration**:
 ```java
 @TargetSystem("redis-cache")
-@ChangeUnit(id = "cache-warming", order = "002", author = "team-platform")
+@Change(id = "cache-warming", order = "20250207_02", author = "team-platform")
 @Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY)
 public class CacheWarmingChange {
 
@@ -312,7 +312,7 @@ public class CacheWarmingChange {
 ```java
 // Event publishing - idempotent with same event key
 @TargetSystem("kafka-events")
-@ChangeUnit(id = "publish-user-events", order = "003", author = "team-events")
+@Change(id = "publish-user-events", order = "20250207_03", author = "team-events")
 @Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY)
 public class PublishUserEvents {
 
@@ -335,7 +335,7 @@ public class PublishUserEvents {
 }
 
 // CREATE IF NOT EXISTS - naturally idempotent
-@ChangeUnit(id = "create-indexes", order = "004", author = "team-dba", transactional = false)
+@Change(id = "create-indexes", order = "20250207_04", author = "team-dba", transactional = false)
 @TargetSystem("user-database")
 @Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY)
 public class CreateIndexes {
@@ -439,7 +439,7 @@ An "issue" is detected when:
 **Best Practice**: Use ALWAYS_RETRY
 ```java
 @Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY)
-@ChangeUnit(id = "publish-user-events", order = "003")
+@Change(id = "publish-user-events", order = "20250207_03")
 public class PublishUserEvents {
     @Execution
     public void publish(KafkaProducer producer) {
@@ -455,7 +455,7 @@ public class PublishUserEvents {
 
 **Best Practice**: MANUAL_INTERVENTION for safety
 ```java
-@ChangeUnit(id = "multi-system-update", order = "004")
+@Change(id = "multi-system-update", order = "20250207_04")
 // Default MANUAL_INTERVENTION ensures consistency
 public class MultiSystemUpdate {
     @Execution
@@ -651,7 +651,7 @@ public class CriticalDataMigration {
 Start with MANUAL_INTERVENTION, move to ALWAYS_RETRY after validation:
 ```java
 // Phase 1: Manual intervention during initial rollout
-@ChangeUnit(id = "feature-v1", order = "001", author = "team-feature")
+@Change(id = "feature-v1", order = "20250207_01", author = "team-feature")
 public class FeatureRollout {
     @Execution
     public void rolloutFeature(FeatureService service) {
@@ -662,7 +662,7 @@ public class FeatureRollout {
 }
 
 // Phase 2: After validation, same change with retry
-@ChangeUnit(id = "feature-v1-stable", order = "002", author = "team-feature")
+@Change(id = "feature-v1-stable", order = "20250207_02", author = "team-feature")
 @Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY)
 public class FeatureRolloutStable {
     @Execution
@@ -677,7 +677,7 @@ public class FeatureRolloutStable {
 ### Pattern 4: Transactional vs Non-Transactional Strategy
 ```java
 // Large bulk operation - non-transactional for performance
-@ChangeUnit(id = "bulk-user-update", order = "005", 
+@Change(id = "bulk-user-update", order = "20250207_05", 
            author = "team-data", transactional = false)
 @TargetSystem("user-database")
 @Recovery(strategy = RecoveryStrategy.MANUAL_INTERVENTION)  
@@ -714,7 +714,7 @@ public class BulkUserUpdate {
 }
 
 // Small critical operation - transactional for safety
-@ChangeUnit(id = "admin-permissions", order = "006", 
+@Change(id = "admin-permissions", order = "20250207_06", 
            author = "team-security", transactional = true)
 @TargetSystem("user-database") 
 @Recovery(strategy = RecoveryStrategy.MANUAL_INTERVENTION)

docs/changes/anatomy-and-structure.md

@@ -15,7 +15,7 @@ Every Change must define these three properties:
 The `id` must be unique across all Changes in your application.
 
 ```java
-@Change(id = "add-user-status", order = "0001", author = "dev-team")
+@Change(id = "add-user-status", author = "dev-team")  // order extracted from filename
 ```
 
 **Rules:**
@@ -28,14 +28,14 @@ ____
 The `order` determines when the Change executes relative to others.
 
 ```java
-@Change(id = "create-indexes", order = "0001", author = "dev-team")
-@Change(id = "migrate-data", order = "0002", author = "dev-team")
-@Change(id = "cleanup-temp-data", order = "0003", author = "dev-team")
+@Change(id = "create-indexes", order = "20250923_01", author = "dev-team")
+@Change(id = "migrate-data", order = "20250923_02", author = "dev-team")
+@Change(id = "cleanup-temp-data", order = "20250923_03", author = "dev-team")
 ```
 
 **Requirements:**
-- Must use zero-padded format: `0001`, `0002`, `0100`, etc.
-- Minimum 4 digits recommended for future expansion
+- Recommended format: `YYYYMMDD_NN` (e.g., `20250923_01`, `20250923_02`)
+- YYYY = year, MM = month, DD = day, NN = sequence number (01-99)
 - Determines execution order across all target systems
 - Cannot be changed once deployed
 
@@ -48,8 +48,8 @@ The `order` determines when the Change executes relative to others.
 - For file/class names:
   - Must start with underscore `_`
   - Order is extracted between the first `_` and the last `_`
-  - Allows intermediate underscores (e.g., `_2025_09_01_09_00_0001_CreateUserTable.java`)
-  - Order extracted: everything between first and last underscore (e.g., `2025_09_01_09_00_0001`)
+  - Recommended format: `YYYYMMDD_NN` (e.g., `_20250923_01_CreateUserTable.java`)
+  - Order extracted: everything between first and last underscore (e.g., `20250923_01`)
 - Orders are evaluated in alphanumeric order
 :::
 
@@ -59,8 +59,8 @@ ____
 Identifies who is responsible for this change.
 
 ```java
-@Change(id = "update-schema", order = "0001", author = "database-team")
-@Change(id = "migrate-users", order = "0002", author = "[email protected]")
+@Change(id = "update-schema", order = "20250923_01", author = "database-team")
+@Change(id = "migrate-users", order = "20250923_02", author = "[email protected]")
 ```
 
 **Best practices:**
@@ -76,7 +76,7 @@ Controls whether the change runs within a transaction (default: `true`).
 ```java
 @Change(
     id = "create-large-index",
-    order = "0001",
+    order = "20250923_01",
     author = "db-team",
     transactional = false  // DDL operations may require this
 )
@@ -95,14 +95,14 @@ Controls how Flamingock handles execution failures (default: `MANUAL_INTERVENTIO
 
 ```java
 // Default behavior (manual intervention)
-@Change(id = "critical-change", order = "0001", author = "team")
+@Change(id = "critical-change", order = "20250923_01", author = "team")
 public class CriticalChange {
     // Execution stops on failure, requires manual resolution
 }
 
 // Automatic retry
 @Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY)
-@Change(id = "idempotent-change", order = "0002", author = "team")
+@Change(id = "idempotent-change", order = "20250923_02", author = "team")
 public class IdempotentChange {
     // Automatically retries on failure until successful
 }
@@ -121,7 +121,7 @@ Briefly describes what the change does, especially useful for complex operations
 ```java
 @Change(
     id = "optimize-user-queries",
-    order = "0001",
+    order = "20250923_01",
     author = "performance-team",
     description = "Add composite index on user table to improve search performance"
 )
@@ -134,8 +134,8 @@ Declares which target system this Change affects.
 
 ```java
 @TargetSystem("user-database")
-@Change(id = "add-user-fields", order = "0001", author = "api-team")
-public class _0001_AddUserFields {
+@Change(id = "add-user-fields", author = "api-team")  // order extracted from filename
+public class _20250923_01_AddUserFields {
     // Implementation
 }
 ```
@@ -147,7 +147,7 @@ Marks the class as a Change and contains all metadata.
 ```java
 @Change(
     id = "migrate-user-data",
-    order = "0001",
+    order = "20250923_01",
     author = "migration-team",
     description = "Migrate legacy user format to new schema",
     transactional = true
@@ -216,20 +216,20 @@ For complete details on target system configuration vs change execution dependen
 
 ## File naming conventions
 
-All Change files must follow the `_XXXX_DescriptiveName` pattern:
+All Change files must follow the `_ORDER_DescriptiveName` pattern, with recommended format `_YYYYMMDD_NN_DescriptiveName`:
 
 ```
-_0001_CreateUserIndexes.java
-_0002_MigrateUserData.java  
-_0003_AddUserStatusColumn.yml
-_0100_OptimizeQueries.java
+_20250923_01_CreateUserIndexes.java
+_20250923_02_MigrateUserData.java
+_20250924_01_AddUserStatusColumn.yaml
+_20250925_01_OptimizeQueries.java
 ```
 
 **Rules:**
-- Start with underscore and zero-padded order
+- Start with underscore and order (recommended: YYYYMMDD_NN format)
 - Use PascalCase for descriptive names
-- Match the `order` property in the annotation
-- Applies to both code (.java/.kt/.groovy) and template (.yml/.json) files
+- Match the `order` property in the annotation if provided
+- Applies to both code (.java/.kt/.groovy) and template (.yaml/.json) files
 
 ## Complete example
 
@@ -239,12 +239,12 @@ Here's a complete Change showing all elements:
 @TargetSystem("user-database")
 @Change(
     id = "add-user-preferences",
-    order = "0001",
+    order = "20250923_01",
     author = "user-experience-team",
     description = "Add preferences object to user documents with default values",
     transactional = true
 )
-public class _0001_AddUserPreferences {
+public class _20250923_01_AddUserPreferences {
 
     @Apply
     public void apply(MongoDatabase database, ClientSession session) {