feat(tools): replace broken main-hand tools

design/log.md

@@ -38,6 +38,13 @@ description: Chronological record of material decisions affecting the Spigot Inv
 - Rejected locked containers, cancelled protection events, non-right-click interactions, and unauthenticated sticks without changing inventories.
 - Added action-bar feedback, documented player behavior, and verified the complete feature with `./gradlew clean check jar`.
 
+## 2026-09-04 — Automatic tool replacement completed
+
+- Added next-tick replacement of broken main-hand tools with exact-material matches from player storage.
+- Main storage is searched before other hotbar slots, and the replacement item is moved intact into the captured selected slot without overwriting a newly occupied slot.
+- Off-hand breaks and unavailable or mismatched replacements leave inventory unchanged.
+- Added player feedback and verified matching, source priority, metadata-preserving movement, safety, and off-hand behavior with automated tests and `./gradlew clean check jar`.
+
 ## 2026-09-04 — Implementation started
 
 - Approved implementation begins with the tested Gradle and Purpur foundation, followed by the Sorting Stick, inventory sorting, and automatic tool replacement.

design/user-stories/us-004-replace-broken-tools.md

@@ -2,7 +2,7 @@
 type: User Story
 title: "US-004: Automatically replace broken tools"
 description: Move an equivalent inventory tool into the player's hand when their current main-hand tool breaks.
-status: in-progress
+status: done
 ---
 
 # US-004: Automatically replace broken tools
@@ -11,15 +11,15 @@ As a **player**, I want an equivalent tool moved into my hand when my current to
 
 ## Acceptance criteria
 
-- [ ] When a player's main-hand tool breaks, the plugin searches the player's inventory for a replacement.
-- [ ] A replacement must have the same tool type and material as the broken tool; for example, a diamond pickaxe replaces only a diamond pickaxe.
-- [ ] Eligible replacements may come from the main storage inventory or another hotbar slot.
-- [ ] The replacement is moved into the currently selected hotbar slot.
-- [ ] Existing durability, enchantments, custom names, persistent data, and other metadata on the replacement are preserved.
-- [ ] No unrelated item is moved when an equivalent replacement is unavailable.
-- [ ] Off-hand tool breakage does not replace the main-hand item.
-- [ ] Cancelled damage or break events do not trigger replacement.
-- [ ] Automated tests cover matching, unavailable replacements, hotbar and main-storage candidates, metadata preservation, and off-hand behavior.
+- [x] When a player's main-hand tool breaks, the plugin searches the player's inventory for a replacement.
+- [x] A replacement must have the same tool type and material as the broken tool; for example, a diamond pickaxe replaces only a diamond pickaxe.
+- [x] Eligible replacements may come from the main storage inventory or another hotbar slot.
+- [x] The replacement is moved into the currently selected hotbar slot.
+- [x] Existing durability, enchantments, custom names, persistent data, and other metadata on the replacement are preserved.
+- [x] No unrelated item is moved when an equivalent replacement is unavailable.
+- [x] Off-hand tool breakage does not replace the main-hand item.
+- [x] Cancelled damage or break events do not trigger replacement.
+- [x] Automated tests cover matching, unavailable replacements, hotbar and main-storage candidates, metadata preservation, and off-hand behavior.
 
 ## Related