feat: implement Masterwork to Master rank trigger

Implements Epic 4.8 - When a character crafts a Masterwork item, they 
immediately reach Master rank (level 10) in all classes associated with 
that recipe's skill requirements.

Changes:
- Added MasterRankAchievedEvent to track Master rank achievements
- Modified CraftingSystem to detect Masterwork outcomes and grant Master rank
- Extracted MasterRankLevel constant to ClassProgressCollection
- Consolidated class progress updates for cleaner code
- Added comprehensive test coverage (4 tests)

This completes Epic 4 (Crafting and Class Progression) - all 8 tasks done.

Closes #39

Author: martincjarvis

docs/plans/rules-engine-design.md

@@ -14,28 +14,29 @@ Build a headless .NET 10 simulation engine that validates game design by running
 
 ### Current Sprint Goal
 
-Complete Epic 4 (Crafting and Class Progression) to enable full crafting mechanics and class unlocking.
+Epic 4 (Crafting and Class Progression) complete! Next: Epic 5 (Economy and Inventory) to enable trading and resource management.
 
 ### Epic Status Overview
 
-| Epic | Title                            | Status         | Progress | GitHub Issue |
-| ---- | -------------------------------- | -------------- | -------- | ------------ |
-| 1    | Project Foundation               | ✅ Complete    | 5/5      | #3           |
-| 2    | Time and Simulation Loop         | ✅ Complete    | 6/6      | #4           |
-| 3    | NPC Decision Making              | ✅ Complete    | 6/6      | #5           |
-| 4    | Crafting and Class Progression   | 🔄 In Progress | 7/8      | #6           |
-| 5    | Economy and Inventory            | ⏳ Planned     | 0/6      | #7           |
-| 6    | Contracts and Commitments        | 🔄 Partial     | 2/6      | #8           |
-| 7    | Settlement and Guild             | ⏳ Planned     | 0/6      | #9           |
-| 8    | Scenario Testing Framework       | ⏳ Planned     | 0/7      | #10          |
-| 9    | Persistence                      | ⏳ Planned     | 0/4      | #11          |
-| 10   | Apprenticeship and Role Stacking | ⏳ Planned     | 0/4      | #12          |
-| 11   | Full Progression Scenario        | ⏳ Planned     | 0/5      | #13          |
-
-**Total Progress**: 26/58 tasks complete (45%)
+| Epic | Title                            | Status      | Progress | GitHub Issue |
+| ---- | -------------------------------- | ----------- | -------- | ------------ |
+| 1    | Project Foundation               | ✅ Complete | 5/5      | #3           |
+| 2    | Time and Simulation Loop         | ✅ Complete | 6/6      | #4           |
+| 3    | NPC Decision Making              | ✅ Complete | 6/6      | #5           |
+| 4    | Crafting and Class Progression   | ✅ Complete | 8/8      | #6           |
+| 5    | Economy and Inventory            | ⏳ Planned  | 0/6      | #7           |
+| 6    | Contracts and Commitments        | 🔄 Partial  | 2/6      | #8           |
+| 7    | Settlement and Guild             | ⏳ Planned  | 0/6      | #9           |
+| 8    | Scenario Testing Framework       | ⏳ Planned  | 0/7      | #10          |
+| 9    | Persistence                      | ⏳ Planned  | 0/4      | #11          |
+| 10   | Apprenticeship and Role Stacking | ⏳ Planned  | 0/4      | #12          |
+| 11   | Full Progression Scenario        | ⏳ Planned  | 0/5      | #13          |
+
+**Total Progress**: 27/58 tasks complete (47%)
 
 ### Recent Completions
 
+- ✅ **2026-01-19**: Epic 4.8 - Masterwork → Master rank trigger (#39, PR #136)
 - ✅ **2026-01-19**: Epic 4.7 - CraftingSystem (#38, PR #135)
 - ✅ **2026-01-19**: Epic 4.6 - CraftingOutcomeRule (#37, PR #134)
 - ✅ **2026-01-19**: Epic 4.5 - Define RecipeDefinition (#36, PR #127, commit 8148f26)
@@ -48,7 +49,8 @@ Complete Epic 4 (Crafting and Class Progression) to enable full crafting mechani
 
 Priority order for remaining work:
 
-1. **Epic 4.8** - #39: Implement Masterwork → Master rank trigger
+1. **Epic 5** - #7: Economy and Inventory (0/6 tasks)
+2. **Epic 6** - #8: Complete Contracts and Commitments (4/6 remaining)
 
 ## Key Design Decisions
 
@@ -250,11 +252,13 @@ _For implementation patterns, examine referenced code paths._
 - ✅ Event emission with outcome details
 - **Verified**: 8 tests pass, crafting produces items and awards XP, all 511 tests pass
 
-**4.8 Implement Masterwork → Master rank trigger** ⏳ _Issue #39_
+**4.8 Implement Masterwork → Master rank trigger** ✅ _Issue #39, PR #136_
 
-- Creating Masterwork immediately grants Master rank
-- Emit event
-- **Verify**: Masterwork creation triggers Master rank
+- ✅ MasterRankAchievedEvent for tracking Master rank achievements
+- ✅ Masterwork outcome immediately grants Master rank (level 10)
+- ✅ Event emission with trigger reason
+- ✅ Handles already-Master characters (no duplicate events)
+- **Verified**: 4 tests pass, Masterwork triggers Master rank, all 515 tests pass
 
 ---
 

src/FantasyRpgWorld.Core/Domain/Components/ClassProgressCollection.cs

@@ -8,6 +8,11 @@ namespace FantasyRpgWorld.Core.Domain.Components;
 /// </summary>
 public readonly record struct ClassProgressCollection
 {
+    /// <summary>
+    /// Master rank level threshold. Achieved when creating a Masterwork item.
+    /// </summary>
+    public const int MasterRankLevel = 10;
+
     private readonly IReadOnlyDictionary<ClassId, ClassProgress> _progressByClass;
 
     public ClassProgressCollection()

src/FantasyRpgWorld.Core/Events/MasterRankAchievedEvent.cs

@@ -0,0 +1,27 @@
+using FantasyRpgWorld.Core.Domain.ValueObjects;
+
+namespace FantasyRpgWorld.Core.Events;
+
+/// <summary>
+/// Event emitted when a character achieves Master rank (level 10) in a class.
+/// Triggered by creating a Masterwork item.
+/// </summary>
+public sealed record MasterRankAchievedEvent : IGameEvent
+{
+    public GameTime OccurredAt { get; init; }
+    public CharacterId CharacterId { get; init; }
+    public ClassId ClassId { get; init; }
+    public string TriggerReason { get; init; }
+
+    public MasterRankAchievedEvent(
+        GameTime occurredAt,
+        CharacterId characterId,
+        ClassId classId,
+        string triggerReason)
+    {
+        OccurredAt = occurredAt;
+        CharacterId = characterId;
+        ClassId = classId;
+        TriggerReason = triggerReason ?? string.Empty;
+    }
+}

src/FantasyRpgWorld.Simulation/Systems/CraftingSystem.cs

@@ -1,4 +1,5 @@
 using FantasyRpgWorld.Core.Definitions;
+using FantasyRpgWorld.Core.Domain.Components;
 using FantasyRpgWorld.Core.Domain.ValueObjects;
 using FantasyRpgWorld.Core.Domain.World;
 using FantasyRpgWorld.Core.Events;
@@ -62,10 +63,11 @@ public SystemUpdateResult Update(WorldState worldState, GameTime currentTime)
                 activeCraft.WorkspaceModifier,
                 _random);
 
-            // Award XP if item was produced
+            // Consolidate all class progress updates
             int xpAwarded = 0;
-            var updatedCharacter = character;
+            var classProgress = character.ClassProgress;
 
+            // Award XP if item was produced
             if (outcomeResult.ItemProduced)
             {
                 // Calculate base XP (simple formula: quality / 2)
@@ -76,20 +78,50 @@ public SystemUpdateResult Update(WorldState worldState, GameTime currentTime)
                 xpAwarded = XpCalculator.CalculateXp(baseXp, totalLevels);
 
                 // Award XP to all applicable classes (classes listed in skill requirements)
-                var classProgress = character.ClassProgress;
                 foreach (var skillReq in recipe.SkillRequirements)
                 {
                     if (classProgress.HasClass(skillReq.ClassId))
                     {
                         classProgress = classProgress.AddXp(skillReq.ClassId, xpAwarded, out _);
                     }
                 }
+            }
 
-                updatedCharacter = updatedCharacter.WithClassProgress(classProgress);
+            // Handle Masterwork → Master rank trigger
+            if (outcomeResult.Outcome == CraftingOutcome.Masterwork)
+            {
+                foreach (var skillReq in recipe.SkillRequirements)
+                {
+                    if (classProgress.HasClass(skillReq.ClassId))
+                    {
+                        int currentLevel = classProgress.GetLevel(skillReq.ClassId);
+                        if (currentLevel < ClassProgressCollection.MasterRankLevel)
+                        {
+                            // Set character to Master rank (level 10)
+                            // Calculate XP needed to reach Master rank
+                            int xpToAdd = 0;
+                            for (int level = currentLevel; level < ClassProgressCollection.MasterRankLevel; level++)
+                            {
+                                xpToAdd += 100 * level; // XP formula from ClassProgressCollection
+                            }
+
+                            classProgress = classProgress.AddXp(skillReq.ClassId, xpToAdd, out _);
+
+                            // Emit Master rank achieved event
+                            events.Add(new MasterRankAchievedEvent(
+                                currentTime,
+                                character.Id,
+                                skillReq.ClassId,
+                                "Masterwork"));
+                        }
+                    }
+                }
             }
 
-            // Clear the active craft
-            updatedCharacter = updatedCharacter.WithActiveCraft(null);
+            // Apply all class progress changes at once
+            var updatedCharacter = character
+                .WithClassProgress(classProgress)
+                .WithActiveCraft(null);
 
             // Update world state
             updatedWorld = updatedWorld.UpdateCharacter(updatedCharacter);