Clarified the Guard on transitions behaviour in the documentation, samples and with the static analysis rules.

Author: leeoades

CHANGELOG.md

@@ -26,13 +26,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
   - Added conceptual pages section for non-feature topics
   - Improved consistency across all documentation pages
   - Added comprehensive index page with links to all documentation
+  - **Clarified first-match semantics** - Made it explicit that transitions evaluate in order and first match wins
+  - Replaced `Guard(() => true)` catch-all pattern with clearer "no guard" approach
 - **🚀 NuGet publishing** - Set up automated Trusted Publishing with GitHub Actions
   - Configured OIDC-based authentication (no long-lived API keys)
   - Added comprehensive PUBLISHING.md guide
   - Fixed symbol package generation for analyzer projects
   - Added proper package descriptions for all projects
   - Separate handling for analyzer vs library packages
 
+### Added
+- **🔍 Enhanced static analysis** - New build-time validations for guard patterns
+  - **Error**: Unguarded transition appearing before other transitions for same trigger (makes subsequent transitions unreachable)
+  - **Warning**: Multiple guarded transitions on same trigger (reminder about first-match semantics)
+  - Helps prevent common guard ordering mistakes
+  - Clear error messages explain first-match behavior
+
 ### Fixed
 - **📦 Analyzer packaging** - Fixed NuGet pack errors for Roslyn analyzer project
   - Disabled symbol package generation for FunctionalStateMachine.Diagrams

docs/guards.md

@@ -2,6 +2,8 @@
 
 Guards let you choose between multiple transitions for the same trigger based on state, data, or trigger properties. They encode business rules directly in your transitions.
 
+> **🎯 First-Match Semantics**: Transitions are evaluated **in order**. The **first matching transition wins** and executes immediately. Subsequent transitions for the same trigger are never checked.
+
 ## Table of Contents
 
 1. [Why Use Guards](#why-use-guards)
@@ -62,50 +64,53 @@ var (newState, newData, commands) = machine.Fire(
 **How it works:**
 - Guard evaluates the predicate `data.CreditScore >= 700`
 - If **true**, the transition executes
-- If **false**, this transition is skipped
+- If **false**, this transition is skipped and the next transition for the same trigger is checked
 
-**What happens if the guard fails?** If no other transition handles this trigger, it's **unhandled** and throws an exception.
+**What happens if the guard fails?** If no other transition handles this trigger, it's **unhandled** and throws an exception (unless you've configured `.OnUnhandled()`).
 
 ---
 
 ## Multiple Guarded Transitions
 
-Handle different cases by defining multiple transitions for the same trigger:
+Handle different cases by defining multiple transitions for the same trigger with **first-match semantics**:
 
 ```csharp
 var machine = StateMachine<LoanState, LoanTrigger, LoanData, LoanCommand>.Create()
     .StartWith(LoanState.Application)
     .For(LoanState.Application)
+        // ⚠️ ORDER MATTERS: First matching guard wins!
         .On<LoanTrigger.Submit>()
-            .Guard(data => data.CreditScore >= 700)        // First guard
+            .Guard(data => data.CreditScore >= 700)        // Checked first
             .Execute(() => new LoanCommand.SendApproval())
             .TransitionTo(LoanState.Approved)
         .On<LoanTrigger.Submit>()
-            .Guard(data => data.CreditScore < 700)         // Second guard
+            .Guard(data => data.CreditScore < 700)         // Checked second
             .Execute(() => new LoanCommand.SendRejection())
             .TransitionTo(LoanState.Rejected)
     .Build();
 ```
 
-**Evaluation order:**  
-Guards are evaluated **in the order you define them**. The **first matching guard wins**.
+**⚠️ First-Match Evaluation:**  
+- Transitions are evaluated **in the order you define them**
+- The **first matching guard wins** and executes
+- Subsequent transitions are **never checked** (short-circuit evaluation)
 
 ```csharp
 // CreditScore = 650
 var (newState, _, commands) = machine.Fire(
     new LoanTrigger.Submit(), 
     LoanState.Application, 
     new LoanData(50000, 650));
-// First guard fails (650 < 700 is false)
-// Second guard passes (650 < 700 is true) ✅
+// First guard fails (650 >= 700 is false) → check next
+// Second guard passes (650 < 700 is true) → EXECUTE, STOP ✅
 // newState == LoanState.Rejected
 ```
 
 ---
 
-## Guard with Multiple Conditions
+## Catch-All Pattern (No Guard)
 
-Guards can check multiple properties:
+For the final "else" case, **omit the guard entirely** instead of using `Guard(data => true)`:
 
 ```csharp
 public sealed record LoanData(decimal Amount, int CreditScore, bool HasCollateral);
@@ -125,15 +130,19 @@ var machine = StateMachine<LoanState, LoanTrigger, LoanData, LoanCommand>.Create
             .Execute(() => new LoanCommand.SendApproval())
             .TransitionTo(LoanState.Approved)
 
-        // Everything else rejected
-        .On<LoanTrigger.Submit>()
-            .Guard(data => true)  // Catch-all guard
+        // Catch-all: everything else rejected (NO GUARD)
+        .On<LoanTrigger.Submit>()  // ← No guard = always matches
             .Execute(() => new LoanCommand.SendRejection())
             .TransitionTo(LoanState.Rejected)
     .Build();
 ```
 
-**Pattern:** Use a catch-all guard (`data => true`) as the last option to ensure all cases are handled.
+**Why no guard?** 
+- A transition with no guard **always matches** (same as `Guard(data => true)`)
+- Clearer intent: "this is the default case"
+- More idiomatic and concise
+
+**Pattern:** Order your transitions from **most specific to least specific**, with the catch-all (no guard) last.
 
 ---
 
@@ -274,9 +283,8 @@ var machine = StateMachine<ATMState, ATMTrigger, ATMData, ATMCommand>.Create()
             .Execute(() => new ATMCommand.ShowMessage("Insufficient funds"))
             .TransitionTo(ATMState.InsufficientFunds)
 
-        // Guard 3: Successful withdrawal (catch-all)
-        .On<ATMTrigger.ConfirmAmount>()
-            .Guard((data, trigger) => true)  // If we got here, all checks passed
+        // Guard 3: Successful withdrawal (no guard = catch-all)
+        .On<ATMTrigger.ConfirmAmount>()  // No guard - if we got here, all checks passed
             .ModifyData((data, trigger) => data with 
             {
                 Balance = data.Balance - trigger.Amount,
@@ -337,29 +345,33 @@ var (state3, _, commands3) = machine.Fire(
 ```
 
 **What's happening:**
-1. Three guards check conditions in order: daily limit, insufficient funds, success
-2. Each guard routes to a different state based on the condition
-3. The success guard modifies data and emits commands
-4. All guards use the same trigger but produce different outcomes
+1. ⚠️ **First-match semantics**: Transitions are evaluated in order
+2. First guard checks daily limit, if it passes → go to DailyLimitReached, STOP
+3. Second guard checks insufficient funds, if it passes → go to InsufficientFunds, STOP
+4. Third transition has no guard (catch-all) → always executes if we reach it
+5. The catch-all modifies data, emits commands, and transitions to Dispensing
 
 ---
 
 ## Best Practices
 
+✅ **⚠️ Remember first-match semantics**  
+Only the **first matching transition executes**. Order matters!
+
 ✅ **Order guards from most specific to most general**  
-Put stricter conditions first, catch-all guards last.
+Put stricter conditions first, catch-all (no guard) last.
 
-✅ **Use a catch-all guard for completeness**  
-`Guard(data => true)` ensures all cases are handled.
+✅ **Omit the guard for catch-all cases**  
+Use no guard instead of `Guard(data => true)` for the final "else" case. It's clearer and more idiomatic.
 
 ✅ **Keep guards pure**  
 Don't perform I/O or side effects in guard predicates. Only inspect data.
 
 ✅ **Consider If/ElseIf/Else for single-state variations**  
 Use guards when you need to go to different states. Use If/Else when you stay in the same state.
 
-❌ **Avoid overlapping guards without intention**  
-If two guards can both be true, only the first will execute.
+❌ **Avoid unguarded transitions before other transitions**  
+An unguarded transition matches everything, making subsequent transitions for the same trigger unreachable. The build-time analyzer will detect this error.
 
 ---
 

docs/immediate-transitions.md

@@ -141,8 +141,7 @@ var machine = StateMachine<ProcessState, ProcessTrigger, ProcessData, ProcessCom
             .Guard(data => data.Score < 30)                 // Very low score
             .Execute(() => new ProcessCommand.SendRejection())
             .TransitionTo(ProcessState.Rejected)
-        .Immediately()
-            .Guard(data => true)                            // Catch-all
+        .Immediately()  // Catch-all: no guard means "always execute"
             .Execute(() => new ProcessCommand.RequestReview())
             .TransitionTo(ProcessState.NeedsReview)
         .Done()
@@ -489,8 +488,7 @@ Not every state needs an immediate transition. Use triggers for external events.
     .Immediately()
         .Guard(data => data.Condition2)
         .TransitionTo(State.Path2)
-    .Immediately()
-        .Guard(data => true)
+    .Immediately()  // No guard = catch-all
         .TransitionTo(State.DefaultPath)
     .Done()
 ```

src/FunctionalStateMachine.Core/StateMachineAnalysis.cs

@@ -235,7 +235,8 @@ private static void DetectCycle(
     }
 
     /// <summary>
-    /// Detect multiple unguarded transitions for the same trigger (ambiguous routing).
+    /// Detect multiple transitions for the same trigger and unreachable transitions.
+    /// Uses first-match semantics: only the first matching transition executes.
     /// </summary>
     private static void AnalyzeAmbiguousTransitions(
         IReadOnlyDictionary<TState, StateMachine<TState, TTrigger, TData, TCommand>.StateDefinition> states,
@@ -249,6 +250,33 @@ private static void AnalyzeAmbiguousTransitions(
             {
                 var triggerKey = transitionKvp.Key;
                 var transitions = transitionKvp.Value;
+                var triggerType = GetTriggerTypeName(triggerKey);
+
+                // Error: Multiple transitions on the same trigger
+                if (transitions.Count > 1)
+                {
+                    // Check if there's an unguarded transition before the last one
+                    for (int i = 0; i < transitions.Count - 1; i++)
+                    {
+                        if (transitions[i].Guard == null)
+                        {
+                            result.AddError(
+                                $"State '{state}' has an unguarded transition for trigger '{triggerType}' at position {i + 1}, " +
+                                "making subsequent transitions unreachable. Only the first matching transition executes (first-match semantics). " +
+                                "Either add a guard to this transition or remove subsequent transitions for this trigger.");
+                        }
+                    }
+
+                    // Warning: Multiple guarded transitions (might be intentional routing, but worth noting)
+                    if (transitions.All(t => t.Guard != null))
+                    {
+                        result.AddWarning(
+                            $"State '{state}' has {transitions.Count} guarded transitions for trigger '{triggerType}'. " +
+                            "Only the first matching guard will execute (first-match semantics). " +
+                            "Ensure guards are ordered from most specific to least specific.");
+                    }
+                }
+
                 // Find unguarded transitions
                 var unguardedTransitions = transitions.Where(t => t.Guard == null).ToList();
 
@@ -262,11 +290,10 @@ private static void AnalyzeAmbiguousTransitions(
                     // Error if they go to different states (ambiguous routing)
                     if (targets.Count > 1)
                     {
-                        var triggerType = GetTriggerTypeName(triggerKey);
                         result.AddError(
-                            $"State '{state}' has ambiguous transitions for trigger '{triggerType}' leading to different states: " +
-                            string.Join(", ", targets.Select(t => $"'{t}'")) +
-                            ". Add guards or consolidate transitions to resolve the ambiguity.");
+                            $"State '{state}' has {unguardedTransitions.Count} unguarded transitions for trigger '{triggerType}' " +
+                            $"leading to different states: {string.Join(", ", targets.Select(t => $"'{t}'"))}. " +
+                            "Add guards or consolidate transitions to resolve the ambiguity.");
                     }
                 }
             }

test/FunctionalStateMachine.Core.Tests/ConfigurationExtensionOverloadTests.cs

@@ -278,7 +278,7 @@ public void Guard_Transition_LabelFuncStateDataTriggerBool_EvaluatesGuard()
             .StartWith(State.Ready)
             .For(State.Ready)
                 .On(Trigger.Go)
-                    .Guard("FullCheck", (State state, Data data, Trigger trigger) => true)
+                    .Guard("FullCheck", (State state, Data data, Trigger trigger) => state == State.Ready)
                     .TransitionTo(State.Done)
             .For(State.Done)
             .Build();
@@ -393,7 +393,7 @@ public void Guard_NoDataTransition_LabelFuncStateTriggerBool_EvaluatesGuard()
             .StartWith(State.Ready)
             .For(State.Ready)
                 .On(Trigger.Go)
-                    .Guard("FullCheck", (State state, Trigger trigger) => true)
+                    .Guard("FullCheck", (State state, Trigger trigger) => state == State.Ready && trigger == Trigger.Go)
                     .TransitionTo(State.Done)
                     .Done()
             .For(State.Done)

test/FunctionalStateMachine.Core.Tests/StateMachineAnalysisTests.cs

@@ -137,15 +137,15 @@ public void Validate_DetectsAmbiguousTransitions()
     {
         var exception = Assert.Throws<InvalidOperationException>(() =>
         {
-            // Multiple transitions are not allowed
+            // Multiple unguarded transitions are not allowed
             var machine = StateMachine<State, Trigger, Data, CommandBase>.Create()
                 .StartWith(State.A)
                 .For(State.A)
                     .On<Trigger.T1Trigger>()
                         .TransitionTo(State.B)
                         .Execute(() => new Command.Noop())
                     .On<Trigger.T1Trigger>()
-                        .TransitionTo(State.C) // Multiple transitions
+                        .TransitionTo(State.C) // Multiple unguarded transitions
                         .Execute(() => new Command.Noop())
                 .For(State.B)
                     .On<Trigger.T1Trigger>()
@@ -156,7 +156,8 @@ public void Validate_DetectsAmbiguousTransitions()
                 .Build();
         });
 
-        Assert.Contains("ambiguous", exception.Message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("unguarded", exception.Message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("unreachable", exception.Message, StringComparison.OrdinalIgnoreCase);
     }
 
     [Fact]
@@ -379,6 +380,88 @@ public void Validate_MarksParentStatesReachable_WhenImmediateTransitionTargetsCh
         Assert.NotNull(machine);
     }
 
+    [Fact]
+    public void Validate_DetectsUnguardedTransitionBeforeOtherTransitions()
+    {
+        // Unguarded transition before other transitions makes them unreachable
+        var exception = Assert.Throws<InvalidOperationException>(() =>
+        {
+            StateMachine<State, Trigger, Data, CommandBase>.Create()
+                .StartWith(State.A)
+                .For(State.A)
+                    .On<Trigger.T1Trigger>()
+                        .TransitionTo(State.B)  // No guard - always matches
+                        .Execute(() => new Command.Noop())
+                    .On<Trigger.T1Trigger>()    // This is unreachable!
+                        .Guard(data => data.Value > 10)
+                        .TransitionTo(State.C)
+                        .Execute(() => new Command.Noop())
+                .For(State.B)
+                    .On<Trigger.T1Trigger>()
+                        .TransitionTo(State.A)
+                .For(State.C)
+                    .On<Trigger.T1Trigger>()
+                        .TransitionTo(State.A)
+                .Build();
+        });
+
+        Assert.Contains("unguarded transition", exception.Message, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("unreachable", exception.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public void Validate_AllowsUnguardedTransitionAsLast()
+    {
+        // Unguarded transition as the last one is the catch-all pattern
+        var machine = StateMachine<State, Trigger, Data, CommandBase>.Create()
+            .StartWith(State.A)
+            .For(State.A)
+                .On<Trigger.T1Trigger>()
+                    .Guard(data => data.Value > 10)
+                    .TransitionTo(State.B)
+                    .Execute(() => new Command.Noop())
+                .On<Trigger.T1Trigger>()  // Catch-all: no guard, last position
+                    .TransitionTo(State.C)
+                    .Execute(() => new Command.Noop())
+            .For(State.B)
+                .On<Trigger.T1Trigger>()
+                    .TransitionTo(State.A)
+            .For(State.C)
+                .On<Trigger.T1Trigger>()
+                    .TransitionTo(State.A)
+            .Build();
+
+        Assert.NotNull(machine);
+    }
+
+    [Fact]
+    public void Validate_WarnsAboutMultipleGuardedTransitions()
+    {
+        // Multiple guarded transitions should produce a warning (but not error)
+        // This is allowed but worth noting to users
+        var machine = StateMachine<State, Trigger, Data, CommandBase>.Create()
+            .StartWith(State.A)
+            .For(State.A)
+                .On<Trigger.T1Trigger>()
+                    .Guard(data => data.Value > 10)
+                    .TransitionTo(State.B)
+                    .Execute(() => new Command.Noop())
+                .On<Trigger.T1Trigger>()
+                    .Guard(data => data.Value <= 10)
+                    .TransitionTo(State.C)
+                    .Execute(() => new Command.Noop())
+            .For(State.B)
+                .On<Trigger.T1Trigger>()
+                    .TransitionTo(State.A)
+            .For(State.C)
+                .On<Trigger.T1Trigger>()
+                    .TransitionTo(State.A)
+            .Build();
+
+        // Should build successfully (warning, not error)
+        Assert.NotNull(machine);
+    }
+
     [Fact]
     public void Validate_MarksGrandparentStatesReachable_WhenTransitionTargetsNestedChild()
     {