cmdx 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a9b1cdaccb648dcffd8c5b50417b2891d2c263f922884b4e8163aa8389a7602
-  data.tar.gz: 7ab3292c7441d0a279c1609e3976c7599ae10ae4168b22aae027667578d0352a
+  metadata.gz: 0b1cd7841d40aeac40b6eb36a7ff87a5ace03deae3496e1aef5cb10e34f8f42d
+  data.tar.gz: 303333d4635690575ceda40a2564be417b47f5ec4c2992af542c509710289ae3
 SHA512:
-  metadata.gz: a3c544688dd90eb3e117460f591cd1d85dd3590a1aae8c90e37930c2728ecab5b1ff8ccce06be2cb894627d5d7beca7edebfa313667879e863c0e5338dc7bc29
-  data.tar.gz: a0b6e9c99fc46d3b4bbc627d9967acb8e39fe0fcf1ff51dcc3ab841acabc7b6d6e1bacf3cbaf4a08f0fc9381b409b2829d5f830ecadeefaab9d84647ce28c7cb
+  metadata.gz: 18cde5cf4b6c7fa974ffb7a3827e09d0a5c2ac5f3c2c01427abbc94de71ef1bc03aee78e25032900761f09c8d39e89e52a4ea1d5fa33e07c86f060b483fe839f
+  data.tar.gz: 5ed05ecdb682ae160be47cf6399c76081486011b6143f95f9884a06b588474ba64e3e000efd72ba2dcd6abb343e3e12985d2691ca15ee7575873f90daff6e70f

data/.cursor/rules/cursor-instructions.mdc

@@ -17,6 +17,11 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Ruby 3.4+
 - RSpec 3.1+
 
+## Development Guidelines
+- Performance is critical - benchmark any changes that could affect speed
+- Follow existing code patterns and conventions
+- Maintain backward compatibility for public API
+
 ## Code Style and Structure
 - Write concise, idiomatic Ruby code with accurate examples
 - Follow Ruby conventions and best practices
@@ -24,6 +29,7 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Prefer iteration and modularization over code duplication
 - Use descriptive variable and method names (e.g., user_signed_in?, calculate_total)
 - Write comprehensive code documentation using the Yardoc format
+- Minimize object allocations in hot paths
 
 ## Naming Conventions
 - Use snake_case for file names, method names, and variables
@@ -35,6 +41,7 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Use Ruby's expressive syntax (e.g., unless, ||=, &.)
 - Prefer double quotes for strings
 - Respect my Rubocop options
+- Run `bundle exec rubocop .` before finalizing any code changes
 
 ## Performance Optimization
 - Use memoization for expensive operations
@@ -50,6 +57,7 @@ Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM
 - Don't test declarative configuration
 - Use appropriate matchers
 - Update tests and update Yardocs after you write code
+- Run `bundle rspec .` before finalizing any code changes
 
 ## Documentation
 - Utilize the YARDoc format when documenting Ruby code

data/.yard-lint.yml

@@ -0,0 +1,174 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+# Global settings for all validators
+AllValidators:
+  # YARD command-line options (applied to all validators by default)
+  YardOptions:
+    - --private
+    - --protected
+
+  # Global file exclusion patterns
+  Exclude:
+    - '\.git'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'spec/**/*'
+    - 'test/**/*'
+
+  # Exit code behavior (error, warning, convention, never)
+  FailOnSeverity: warning
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  # MinCoverage: 80.0
+
+  # Diff mode settings
+  DiffMode:
+    # Default base ref for --diff (auto-detects main/master if not specified)
+    DefaultBaseRef: ~
+
+# Documentation validators
+Documentation/UndocumentedObjects:
+  Description: 'Checks for classes, modules, and methods without documentation.'
+  Enabled: false
+  Severity: warning
+  ExcludedMethods:
+    - 'initialize/0'  # Exclude parameter-less initialize
+    - '/^_/'          # Exclude private methods (by convention)
+
+Documentation/UndocumentedMethodArguments:
+  Description: 'Checks for method parameters without @param tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: warning
+
+Documentation/MarkdownSyntax:
+  Description: 'Detects common markdown syntax errors in documentation.'
+  Enabled: true
+  Severity: warning
+
+# Tags validators
+Tags/Order:
+  Description: 'Enforces consistent ordering of YARD tags.'
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - param
+    - option
+    - return
+    - raise
+    - example
+
+Tags/InvalidTypes:
+  Description: 'Validates type definitions in @param, @return, @option tags.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: warning
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: convention
+  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Description: 'Validates type annotation position in tags.'
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+  #                or 'type_first' (@param [Type] name)
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: 'Enforces @api tags on public objects.'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  Enabled: true
+  Severity: warning
+
+# Warnings validators - catches YARD parser errors
+Warnings/UnknownTag:
+  Description: 'Detects unknown YARD tags.'
+  Enabled: false
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: 'Detects unknown YARD directives.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: 'Detects malformed tag syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: 'Detects malformed directive syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: 'Detects duplicate @param tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: 'Detects @param tags for non-existent parameters.'
+  Enabled: true
+  Severity: error
+
+# Semantic validators
+Semantic/AbstractMethods:
+  Description: 'Ensures @abstract methods do not have real implementations.'
+  Enabled: true
+  Severity: warning

data/CHANGELOG.md

@@ -6,6 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.13.0] - 2025-12-23
+
+### Added
+
+- Added task execution rollback tracking and logging
+- Added `dry_run` option to task execution with inheritance support for nested tasks
+- Added context `delete` alias for `delete!`
+- Added context `merge` alias for `merge!`
+
+## [1.12.0] - 2025-12-18
+
+### Added
+- Added active record database transaction example
+- Added Sentry error tracking example
+- Added Redis idempotency example
+- Added Flipper feature flag example
+
+### Updated
+- Remove `handle_*` methods and provide `on(*states_or_statuses)` method for more flexibility
+- Optimize logging ancestor lookup
+- Use chop instead of range for better string performance
+- Update boolean coercion `TRUTHY` and `FALSEY` regexp to be case insensitive
+- Improve YARD documentation with `yard-lint`
+
 ## [1.11.0] - 2025-11-08
 
 ### Updated

data/docs/attributes/definitions.md

@@ -4,6 +4,10 @@ Attributes define your task's interface with automatic validation, type coercion
 
 ## Declarations
 
+!!! warning "Important"
+
+    Attributes are order-dependent, so if you need to reference them as a source or use them in conditions, make sure they’re defined in the correct order.
+
 !!! tip
 
     Prefer using the `required` and `optional` alias for `attributes` for brevity and to clearly signal intent.
@@ -54,7 +58,7 @@ class PublishArticle < CMDx::Task
 
   # Conditionally required
   required :publisher, if: :magazine?
-  required :approver, unless: proc { status == :published }
+  attribute :approver, required: true, unless: proc { status == :published }
 
   def work
     title     #=> "Getting Started with Ruby"

data/docs/attributes/validations.md

@@ -14,10 +14,10 @@ class ProcessSubscription < CMDx::Task
   attribute :user_id, presence: true
 
   # String with length constraints
-  attribute :preferences, length: { minimum: 10, maximum: 500 }
+  optional :preferences, length: { minimum: 10, maximum: 500 }
 
   # Numeric range validation
-  attribute :tier_level, inclusion: { in: 1..5 }
+  required :tier_level, inclusion: { in: 1..5 }
 
   # Format validation for email
   attribute :contact_email, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
@@ -46,6 +46,42 @@ ProcessSubscription.execute(
 
 ### Common Options
 
+```ruby
+class ProcessProduct < CMDx::Task
+  # Allow nil
+  attribute :tier_level, inclusion: {
+    in: 1..5,
+    allow_nil: true
+  }
+
+  # Conditionals
+  optional :contact_email, format: {
+    with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+    if: ->(value) { value.includes?("@") }
+  }
+  required :status, exclusion: {
+    in: %w[recalled archived],
+    unless: :product_sunsetted?
+  }
+
+  # Custom message
+  attribute :title, length: {
+    within: 5..100,
+    message: "must be in optimal size"
+  }
+
+  def work
+    # Your logic here...
+  end
+
+  private
+
+  def product_defunct?(value)
+    context.company.out_of_business? || value == "deprecated"
+  end
+end
+```
+
 This list of options is available to all validators:
 
 | Option | Description |
@@ -261,10 +297,15 @@ Validation failures provide detailed, structured error messages:
 
 ```ruby
 class CreateProject < CMDx::Task
-  attribute :project_name, presence: true, length: { minimum: 3, maximum: 50 }
-  attribute :budget, numeric: { greater_than: 1000, less_than: 1000000 }
-  attribute :priority, inclusion: { in: [:low, :medium, :high] }
-  attribute :contact_email, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+  attribute :project_name,
+    presence: true,
+    length: { minimum: 3, maximum: 50 }
+  optional :budget,
+    numeric: { greater_than: 1000, less_than: 1000000 }
+  required :priority,
+    inclusion: { in: [:low, :medium, :high] }
+  attribute :contact_email,
+    format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
 
   def work
     # Your logic here...

data/docs/basics/execution.md

@@ -11,6 +11,33 @@ Both methods return results, but handle failures differently:
 | `execute` | Always returns `CMDx::Result` | Never raises | Predictable result handling |
 | `execute!` | Returns `CMDx::Result` on success | Raises `CMDx::Fault` when skipped or failed | Exception-based control flow |
 
+```mermaid
+flowchart LR
+    subgraph Methods
+        E[execute]
+        EB[execute!]
+    end
+
+    subgraph Returns [Returns CMDx::Result]
+        Success
+        Failed
+        Skipped
+    end
+
+    subgraph Raises [Raises CMDx::Fault]
+        FailFault
+        SkipFault
+    end
+
+    E --> Success
+    E --> Failed
+    E --> Skipped
+
+    EB --> Success
+    EB --> FailFault
+    EB --> SkipFault
+```
+
 ## Non-bang Execution
 
 Always returns a `CMDx::Result`, never raises exceptions. Perfect for most use cases.
@@ -94,3 +121,32 @@ result.chain        #=> Task execution chain
 result.context      #=> Context with all task data
 result.metadata     #=> Hash with execution metadata
 ```
+
+## Dry Run
+
+Execute tasks in dry-run mode to simulate execution without performing side effects. Pass `dry_run: true` in the context when initializing or executing the task.
+
+Inside your task, use the `dry_run?` method to conditionally skip side effects.
+
+```ruby
+class CloseStripeCard < CMDx::Task
+  def work
+    context.stripe_result =
+      if dry_run?
+        FactoryBot.build(:stripe_closed_card)
+      else
+        StripeApi.close_card(context.card_id)
+      end
+  end
+end
+
+# Execute in dry-run mode
+result = CloseStripeCard.execute(card_id: "card_abc123", dry_run: true)
+result.success? # => true
+
+# FactoryBot object
+result.context.stripe_result = {
+  card_id: "card_abc123",
+  status: "closed"
+}
+```

data/docs/basics/setup.md

@@ -29,13 +29,14 @@ IncompleteTask.execute #=> raises CMDx::UndefinedMethodError
 Undo any operations linked to the given status, helping to restore a pristine state.
 
 ```ruby
-class ValidateDocument < CMDx::Task
+class ChargeCard < CMDx::Task
   def work
-    # Your logic here...
+    # Your logic here, ex: charge $100
   end
 
+  # Called automatically if a later step in the workflow fails
   def rollback
-    # Your undo logic...
+    # Your undo logic, ex: void $100 charge
   end
 end
 ```
@@ -70,6 +71,28 @@ end
 
 Tasks follow a predictable execution pattern:
 
+```mermaid
+stateDiagram-v2
+    Initialized: Instantiation
+    Initialized --> Validating: execute
+    Validating --> Executing: Valid?
+    Validating --> Failed: Invalid
+    Executing --> Success: Work done
+    Executing --> Skipped: skip!
+    Executing --> Failed: fail! / Exception
+    Executed
+
+    state Executed {
+        Success
+        Skipped
+        Failed
+        Rollback
+
+        Skipped --> Rollback
+        Failed --> Rollback
+    }
+```
+
 !!! danger "Caution"
 
     Tasks are single-use objects. Once executed, they're frozen and immutable.

data/docs/deprecation.md

@@ -32,8 +32,6 @@ Allow execution while tracking deprecation in logs. Ideal for gradual migrations
 ```ruby
 class ProcessLegacyFormat < CMDx::Task
   settings(deprecated: :log)
-
-  # Same
   settings(deprecated: true)
 
   def work

data/docs/getting_started.md

@@ -43,6 +43,13 @@ If not using Rails, manually copy the [configuration file](https://github.com/dr
 
 CMDx embraces the Compose, Execute, React, Observe (CERO, pronounced "zero") pattern—a simple yet powerful approach to building reliable business logic.
 
+```mermaid
+flowchart LR
+    Compose --> Execute
+    Execute --> React
+    Execute -.-> Observe
+```
+
 ### Compose
 
 Build reusable, single-responsibility tasks with typed attributes, validation, and callbacks. Tasks can be chained together in workflows to create complex business processes from simple building blocks.
@@ -93,6 +100,10 @@ I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
 index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
 ```
 
+!!! note
+
+    This represents a log-only event-sourcing approach, enabling full traceability and a complete, time-ordered view of system behavior.
+
 ## Task Generator
 
 Generate new CMDx tasks quickly using the built-in generator:

data/docs/logging.md

@@ -18,20 +18,16 @@ Sample output:
 
 ```log
 <!-- Success (INFO level) -->
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- GenerateInvoice:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
+I, [2025-12-23T17:04:07.292614Z #20108] INFO -- cmdx: {index: 1, chain_id: "019b4c2b-087b-79be-8ef2-96c11b659df5", type: "Task", tags: [], class: "GenerateInvoice", dry_run: false, id: "019b4c2b-0878-704d-ba0b-daa5410123ec", state: "complete", status: "success", outcome: "success", metadata: {runtime: 187}}
 
-<!-- Skipped (WARN level) -->
-W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
+<!-- Skipped (INFO level) -->
+I, [2025-12-23T17:04:11.496881Z #20139] INFO -- cmdx: {index: 2, chain_id: "019b4c2b-18e8-7af6-a38b-63b042c4fbed", type: "Task", tags: [], class: "ValidateCustomer", dry_run: false, id: "019b4c2b-18e5-7230-af7e-5b4a4bd7cda2", state: "interrupted", status: "skipped", outcome: "skipped", metadata: {}, reason: "Customer already validated", cause: #<CMDx::SkipFault: Customer already validated>, rolled_back: false}
 
-<!-- Failed (ERROR level) -->
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
+<!-- Failed (INFO level) -->
+I, [2025-12-23T17:04:15.875306Z #20173] INFO -- cmdx: {index: 3, chain_id: "019b4c2b-2a02-7dbc-b713-b20a7379704f", type: "Task", tags: [], class: "CalculateTax", dry_run: false, id: "019b4c2b-2a00-70b7-9fab-2f14db9139ef", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}
 
 <!-- Failed Chain -->
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-index=3 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="BillingWorkflow"  state="interrupted" status="failed" caused_failure={index: 2, class: "CalculateTax", status: "failed"} threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
+I, [2025-12-23T17:04:20.972539Z #20209] INFO -- cmdx: {index: 0, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Workflow", tags: [], class: "BillingWorkflow", dry_run: false, id: "019b4c2b-3de6-70b9-9c16-5be13b1a463c", state: "interrupted", status: "failed", outcome: "interrupted", metadata: {}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false, threw_failure: {index: 3, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Task", tags: [], class: "CalculateTax", id: "019b4c2b-3dec-70b3-969b-c5b7896e3b27", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}, caused_failure: {index: 3, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Task", tags: [], class: "CalculateTax", id: "019b4c2b-3dec-70b3-969b-c5b7896e3b27", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}}
 ```
 
 !!! tip

data/docs/outcomes/result.md

@@ -30,7 +30,7 @@ result.metadata #=> { error_code: "BUILD_TOOL.NOT_FOUND" }
 
 ## Lifecycle Information
 
-Check execution state and status with predicate methods:
+Check execution state, status, and rollback with predicate methods:
 
 ```ruby
 result = BuildApplication.execute(version: "1.2.3")
@@ -48,6 +48,9 @@ result.skipped?     #=> false (not skipped)
 # Outcome categorization
 result.good?        #=> true (success or skipped)
 result.bad?         #=> false (skipped or failed)
+
+# Rollback Status
+result.rolled_back? #=> true (execution was rolled back)
 ```
 
 ## Outcome Analysis
@@ -126,19 +129,20 @@ result = BuildApplication.execute(version: "1.2.3")
 
 # Status-based handlers
 result
-  .handle_success { |result| notify_deployment_ready(result) }
-  .handle_failed { |result| handle_build_failure(result) }
-  .handle_skipped { |result| log_skip_reason(result) }
+  .on(:success) { |result| notify_deployment_ready(result) }
+  .on(:failed) { |result| handle_build_failure(result) }
+  .on(:skipped) { |result| log_skip_reason(result) }
 
 # State-based handlers
 result
-  .handle_complete { |result| update_build_status(result) }
-  .handle_interrupted { |result| cleanup_partial_artifacts(result) }
+  .on(:complete) { |result| update_build_status(result) }
+  .on(:interrupted) { |result| cleanup_partial_artifacts(result) }
+  .on(:executed) { |result| alert_operations_team(result) } #=> .on(:complete, :interrupted)
 
 # Outcome-based handlers
 result
-  .handle_good { |result| increment_success_counter(result) }
-  .handle_bad { |result| alert_operations_team(result) }
+  .on(:good) { |result| increment_success_counter(result) } #=> .on(:success, :skipped)
+  .on(:bad) { |result| alert_operations_team(result) }      #=> .on(:failed, :skipped)
 ```
 
 ## Pattern Matching

data/docs/outcomes/states.md

@@ -53,14 +53,14 @@ result.executed?    #=> true (complete OR interrupted)
 
 ## Handlers
 
-Handle lifecycle events with state-based handlers. Use `handle_executed` for cleanup that runs regardless of outcome:
+Handle lifecycle events with state-based handlers. Use `on(:executed)` for cleanup that runs regardless of outcome:
 
 ```ruby
 result = ProcessVideoUpload.execute
 
 # Individual state handlers
 result
-  .handle_complete { |result| send_upload_notification(result) }
-  .handle_interrupted { |result| cleanup_temp_files(result) }
-  .handle_executed { |result| log_upload_metrics(result) }
+  .on(:complete) { |result| send_upload_notification(result) }
+  .on(:interrupted) { |result| cleanup_temp_files(result) }
+  .on(:executed) { |result| log_upload_metrics(result) } #=> .on(:complete, :interrupted)
 ```

data/docs/outcomes/statuses.md

@@ -47,19 +47,19 @@ result.bad?     #=> true if skipped OR failed (not success)
 
 ## Handlers
 
-Branch business logic with status-based handlers. Use `handle_good` and `handle_bad` for success/skip vs failed outcomes:
+Branch business logic with status-based handlers. Use `on(:good)` and `on(:bad)` for success/skip vs failed outcomes:
 
 ```ruby
 result = ProcessNotification.execute
 
 # Individual status handlers
 result
-  .handle_success { |result| mark_notification_sent(result) }
-  .handle_skipped { |result| log_notification_skipped(result) }
-  .handle_failed { |result| queue_retry_notification(result) }
+  .on(:success) { |result| mark_notification_sent(result) }
+  .on(:skipped) { |result| log_notification_skipped(result) }
+  .on(:failed){ |result| queue_retry_notification(result) }
 
 # Outcome-based handlers
 result
-  .handle_good { |result| update_message_stats(result) }
-  .handle_bad { |result| track_delivery_failure(result) }
+  .on(:good) { |result| update_message_stats(result) }  #=> .on(:success, :skipped)
+  .on(:bad) { |result| track_delivery_failure(result) } #=> .on(:failed, :skipped)
 ```

data/docs/tips_and_tricks.md

@@ -147,7 +147,11 @@ end
 
 ## Useful Examples
 
+- [Active Record Database Transaction](https://github.com/drexed/cmdx/blob/main/examples/active_record_database_transaction.md)
 - [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
+- [Flipper Feature Flags](https://github.com/drexed/cmdx/blob/main/examples/flipper_feature_flags.md)
 - [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)
+- [Redis Idempotency](https://github.com/drexed/cmdx/blob/main/examples/redis_idempotency.md)
+- [Sentry Error Tracking](https://github.com/drexed/cmdx/blob/main/examples/sentry_error_tracking.md)
 - [Sidekiq Async Execution](https://github.com/drexed/cmdx/blob/main/examples/sidekiq_async_execution.md)
 - [Stoplight Circuit Breaker](https://github.com/drexed/cmdx/blob/main/examples/stoplight_circuit_breaker.md)

data/examples/active_record_database_transaction.md

@@ -0,0 +1,27 @@
+# Active Record Query Tagging
+
+Wrap task or workflow execution in a database transaction. This is essential for data integrity when multiple steps modify the database.
+
+### Setup
+
+```ruby
+# lib/cmdx_database_transaction_middleware.rb
+class CmdxDatabaseTransactionMiddleware
+  def self.call(task, **options, &)
+    ActiveRecord::Base.transaction(requires_new: true, &)
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxDatabaseTransactionMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```