feat(tools): replace broken main-hand tools

README.md

@@ -29,6 +29,20 @@ Stick
 
 Either storage-block variant produces one Sorting Stick.
 
+## Sorting inventories
+
+Hold an authentic Sorting Stick and right-click:
+
+- A chest or either half of a double chest to sort its complete inventory.
+- A barrel to sort its inventory.
+- Air or another block to sort player inventory slots 9–35.
+
+Player hotbar, armor, and off-hand slots remain unchanged during player sorting. Compatible stacks are consolidated first, then items are ordered alphabetically by Minecraft material. Dissimilar metadata variants of the same material retain their relative order. Locked containers and interactions cancelled by protection plugins are not sorted.
+
+## Automatic tool replacement
+
+When a main-hand tool breaks, an item with the exact same material is moved into the broken tool's selected hotbar slot on the next server tick. Main-storage candidates are preferred before tools in other hotbar slots. The complete replacement item is moved unchanged, preserving durability, enchantments, custom names, and other metadata. Off-hand breaks are ignored, and no unrelated item is moved when a match is unavailable.
+
 ## Releases
 
 Gitea Actions checks pushes and pull requests and stores a development JAR. Pull requests validate conventional commits. Main-branch conventional commits drive semantic releases when the repository defines a `RELEASE_TOKEN` with contents-write permission.

design/log.md

@@ -19,6 +19,32 @@ description: Chronological record of material decisions affecting the Spigot Inv
 - The Sorting Stick uses a vertical recipe in the crafting grid's center column: a Chest or Barrel above Redstone Dust, with a Stick at the bottom.
 - Either storage-block variant produces one Sorting Stick.
 
+## 2026-09-04 — Build and release foundation completed
+
+- Added the Java 25 Gradle build, Purpur API dependency, strict compiler linting, JUnit 5 lifecycle, plugin metadata, and initial plugin entry point.
+- Added Gitea CI, conventional-commit validation for pull requests, development artifacts, semantic releases, and release-asset upload.
+- Verified `./gradlew clean check jar`, successful main and tag CI runs, and release `v1.0.0` with `spigot-inventory-helper-1.0.0.jar` attached.
+
+## 2026-09-04 — Sorting Stick completed
+
+- Added a gold-named, glinting Sorting Stick authenticated by persistent item metadata.
+- Registered equivalent chest and barrel recipe variants matching the approved center-column shape.
+- Verified recipe specification, registration, output, item appearance, identity, and renamed-stick rejection with automated tests and `./gradlew clean check jar`.
+
+## 2026-09-04 — Inventory sorting completed
+
+- Added metadata-preserving stack consolidation and stable alphabetical ordering by Minecraft material.
+- Added Sorting Stick interactions for single and double chests, barrels, and player main-storage slots while preserving hotbar, armor, and off-hand slots.
+- 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-001-build-and-release-plugin.md

@@ -2,7 +2,7 @@
 type: User Story
 title: "US-001: Build and release the plugin"
 description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases.
-status: in-progress
+status: done
 ---
 
 # US-001: Build and release the plugin
@@ -11,15 +11,15 @@ As a **plugin maintainer**, I want repeatable builds and automated releases so t
 
 ## Acceptance criteria
 
-- [ ] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain.
-- [ ] Compiler lint warnings fail the build.
-- [ ] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
-- [ ] Pushes and pull requests build and test the plugin in Gitea Actions.
-- [ ] Pull requests validate conventional commit messages.
-- [ ] CI stores a development JAR as a workflow artifact.
-- [ ] Main-branch conventional commits drive semantic versioning.
-- [ ] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
-- [ ] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Inventory Helper names and identifiers.
+- [x] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain.
+- [x] Compiler lint warnings fail the build.
+- [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
+- [x] Pushes and pull requests build and test the plugin in Gitea Actions.
+- [x] Pull requests validate conventional commit messages.
+- [x] CI stores a development JAR as a workflow artifact.
+- [x] Main-branch conventional commits drive semantic versioning.
+- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
+- [x] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Inventory Helper names and identifiers.
 
 ## Related
 

design/user-stories/us-002-craft-sorting-stick.md

@@ -2,7 +2,7 @@
 type: User Story
 title: "US-002: Craft a Sorting Stick"
 description: Let players craft a recognizable utility item that invokes inventory sorting.
-status: backlog
+status: done
 ---
 
 # US-002: Craft a Sorting Stick
@@ -11,14 +11,14 @@ As a **player**, I want to craft a recognizable Sorting Stick so that I can invo
 
 ## Acceptance criteria
 
-- [ ] The plugin registers a vertical shaped recipe with a Chest or Barrel above Redstone Dust and Redstone Dust above a Stick.
-- [ ] The three ingredients occupy the center column of the 3×3 crafting grid.
-- [ ] Either the Chest or Barrel recipe variant produces one Sorting Stick.
-- [ ] The Sorting Stick has a distinct player-facing name and appearance.
-- [ ] The item is identified using persistent item metadata rather than its display name alone.
-- [ ] Renamed ordinary sticks cannot trigger sorting.
-- [ ] Automated tests cover recipe registration, the exact shape, both storage-block variants, output quantity, and resulting item identity.
-- [ ] The crafting recipe and both accepted variants are documented for players.
+- [x] The plugin registers a vertical shaped recipe with a Chest or Barrel above Redstone Dust and Redstone Dust above a Stick.
+- [x] The three ingredients occupy the center column of the 3×3 crafting grid.
+- [x] Either the Chest or Barrel recipe variant produces one Sorting Stick.
+- [x] The Sorting Stick has a distinct player-facing name and appearance.
+- [x] The item is identified using persistent item metadata rather than its display name alone.
+- [x] Renamed ordinary sticks cannot trigger sorting.
+- [x] Automated tests cover recipe registration, the exact shape, both storage-block variants, output quantity, and resulting item identity.
+- [x] The crafting recipe and both accepted variants are documented for players.
 
 ## Related
 

design/user-stories/us-003-sort-inventories.md

@@ -2,7 +2,7 @@
 type: User Story
 title: "US-003: Sort containers and player inventory"
 description: Let players use a Sorting Stick to consolidate and organize supported storage or their main inventory.
-status: backlog
+status: done
 ---
 
 # US-003: Sort containers and player inventory
@@ -11,18 +11,18 @@ As a **player holding a Sorting Stick**, I want to sort storage containers or my
 
 ## Acceptance criteria
 
-- [ ] Using the Sorting Stick on a chest sorts the complete chest inventory.
-- [ ] Using it on either half of a double chest sorts the combined inventory.
-- [ ] Using it on a barrel sorts that barrel.
-- [ ] Using it without targeting a supported container sorts the player's main storage slots.
-- [ ] Player hotbar, armor, and off-hand slots are not changed during player-inventory sorting.
-- [ ] Compatible partial stacks are consolidated without exceeding item stack limits.
-- [ ] Remaining stacks are placed in a deterministic, documented order.
-- [ ] Sorting preserves item quantities and all item metadata exactly.
-- [ ] Sorting respects cancelled interactions and normal container-access protections.
-- [ ] Unsupported or inaccessible targets fail safely without changing an inventory.
-- [ ] Sorting provides concise player feedback without opening the target container.
-- [ ] Automated tests cover single chests, double chests, barrels, player inventory boundaries, stack consolidation, metadata preservation, and rejected interactions.
+- [x] Using the Sorting Stick on a chest sorts the complete chest inventory.
+- [x] Using it on either half of a double chest sorts the combined inventory.
+- [x] Using it on a barrel sorts that barrel.
+- [x] Using it without targeting a supported container sorts the player's main storage slots.
+- [x] Player hotbar, armor, and off-hand slots are not changed during player-inventory sorting.
+- [x] Compatible partial stacks are consolidated without exceeding item stack limits.
+- [x] Remaining stacks are placed in a deterministic, documented order.
+- [x] Sorting preserves item quantities and all item metadata exactly.
+- [x] Sorting respects cancelled interactions and normal container-access protections.
+- [x] Unsupported or inaccessible targets fail safely without changing an inventory.
+- [x] Sorting provides concise player feedback without opening the target container.
+- [x] Automated tests cover single chests, double chests, barrels, player inventory boundaries, stack consolidation, metadata preservation, and rejected interactions.
 
 ## Related
 

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: backlog
+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
 

src/main/java/games/dmg/spigotinventoryhelper/BrokenToolListener.java

@@ -0,0 +1,58 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.Objects;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.Material;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.Listener;
+import org.bukkit.event.player.PlayerItemBreakEvent;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.bukkit.plugin.Plugin;
+
+public final class BrokenToolListener implements Listener {
+    private final ToolReplacementService replacements;
+    private final TaskScheduler scheduler;
+
+    public BrokenToolListener(Plugin plugin, ToolReplacementService replacements) {
+        this(replacements, task -> plugin.getServer().getScheduler().runTask(plugin, task));
+    }
+
+    BrokenToolListener(ToolReplacementService replacements, TaskScheduler scheduler) {
+        this.replacements = Objects.requireNonNull(replacements, "replacements");
+        this.scheduler = Objects.requireNonNull(scheduler, "scheduler");
+    }
+
+    @EventHandler(priority = EventPriority.MONITOR)
+    public void onItemBreak(PlayerItemBreakEvent event) {
+        Player player = event.getPlayer();
+        PlayerInventory inventory = player.getInventory();
+        ItemStack broken = event.getBrokenItem();
+        if (inventory.getItemInMainHand() != broken) {
+            return;
+        }
+
+        Material material = broken.getType();
+        int selectedSlot = inventory.getHeldItemSlot();
+        scheduler.schedule(() -> {
+            if (replacements.replace(inventory, material, selectedSlot)) {
+                player.sendActionBar(Component.text(
+                    "Equipped another " + readableName(material) + ".",
+                    NamedTextColor.GREEN
+                ));
+            }
+        });
+    }
+
+    private static String readableName(Material material) {
+        return material.name().toLowerCase(java.util.Locale.ROOT).replace('_', ' ');
+    }
+
+    @FunctionalInterface
+    interface TaskScheduler {
+        void schedule(Runnable task);
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/InventorySorter.java

@@ -0,0 +1,58 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Objects;
+import org.bukkit.Material;
+import org.bukkit.inventory.ItemStack;
+
+public final class InventorySorter {
+    public ItemStack[] sort(ItemStack[] contents) {
+        Objects.requireNonNull(contents, "contents");
+        List<ItemStack> items = Arrays.stream(contents)
+            .filter(Objects::nonNull)
+            .filter(item -> item.getType() != Material.AIR)
+            .filter(item -> item.getAmount() > 0)
+            .map(ItemStack::clone)
+            .sorted(Comparator.comparing(item -> item.getType().name()))
+            .toList();
+
+        List<ItemStack> packed = new ArrayList<>();
+        for (ItemStack item : items) {
+            pack(item, packed);
+        }
+
+        ItemStack[] sorted = new ItemStack[contents.length];
+        for (int slot = 0; slot < packed.size(); slot++) {
+            sorted[slot] = packed.get(slot);
+        }
+        return sorted;
+    }
+
+    private static void pack(ItemStack item, List<ItemStack> packed) {
+        int remaining = item.getAmount();
+        for (ItemStack existing : packed) {
+            if (!existing.isSimilar(item) || existing.getAmount() >= existing.getMaxStackSize()) {
+                continue;
+            }
+            int transferred = Math.min(
+                remaining,
+                existing.getMaxStackSize() - existing.getAmount()
+            );
+            existing.setAmount(existing.getAmount() + transferred);
+            remaining -= transferred;
+            if (remaining == 0) {
+                return;
+            }
+        }
+        while (remaining > 0) {
+            ItemStack stack = item.clone();
+            int amount = Math.min(remaining, stack.getMaxStackSize());
+            stack.setAmount(amount);
+            packed.add(stack);
+            remaining -= amount;
+        }
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/InventorySortingService.java

@@ -0,0 +1,39 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.Arrays;
+import java.util.Objects;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+
+public final class InventorySortingService {
+    private static final int HOTBAR_SIZE = 9;
+    private static final int PLAYER_STORAGE_SIZE = 36;
+
+    private final InventorySorter sorter;
+
+    public InventorySortingService(InventorySorter sorter) {
+        this.sorter = Objects.requireNonNull(sorter, "sorter");
+    }
+
+    public void sortPlayerMainStorage(PlayerInventory inventory) {
+        Objects.requireNonNull(inventory, "inventory");
+        ItemStack[] storage = inventory.getStorageContents().clone();
+        if (storage.length < PLAYER_STORAGE_SIZE) {
+            throw new IllegalArgumentException("Player storage must contain 36 slots");
+        }
+        ItemStack[] mainStorage = Arrays.copyOfRange(
+            storage,
+            HOTBAR_SIZE,
+            PLAYER_STORAGE_SIZE
+        );
+        ItemStack[] sorted = sorter.sort(mainStorage);
+        System.arraycopy(sorted, 0, storage, HOTBAR_SIZE, sorted.length);
+        inventory.setStorageContents(storage);
+    }
+
+    public void sortContainer(Inventory inventory) {
+        Objects.requireNonNull(inventory, "inventory");
+        inventory.setContents(sorter.sort(inventory.getContents()));
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/SortingStickItemFactory.java

@@ -0,0 +1,58 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.Objects;
+import java.util.function.Supplier;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.ItemMeta;
+import org.bukkit.persistence.PersistentDataType;
+
+public final class SortingStickItemFactory {
+    private static final byte AUTHENTIC_MARKER = 1;
+
+    private final NamespacedKey identityKey;
+    private final Supplier<ItemStack> itemSupplier;
+
+    public SortingStickItemFactory(NamespacedKey identityKey) {
+        this(identityKey, () -> new ItemStack(Material.STICK));
+    }
+
+    SortingStickItemFactory(NamespacedKey identityKey, Supplier<ItemStack> itemSupplier) {
+        this.identityKey = Objects.requireNonNull(identityKey, "identityKey");
+        this.itemSupplier = Objects.requireNonNull(itemSupplier, "itemSupplier");
+    }
+
+    public ItemStack create() {
+        ItemStack item = itemSupplier.get();
+        item.setType(Material.STICK);
+        item.setAmount(1);
+        ItemMeta metadata = Objects.requireNonNull(item.getItemMeta(), "Stick metadata");
+        metadata.displayName(Component.text("Sorting Stick", NamedTextColor.GOLD));
+        metadata.setEnchantmentGlintOverride(true);
+        metadata.getPersistentDataContainer().set(
+            identityKey,
+            PersistentDataType.BYTE,
+            AUTHENTIC_MARKER
+        );
+        item.setItemMeta(metadata);
+        return item;
+    }
+
+    public boolean isSortingStick(ItemStack item) {
+        if (item == null || item.getType() != Material.STICK || !item.hasItemMeta()) {
+            return false;
+        }
+        ItemMeta metadata = item.getItemMeta();
+        if (metadata == null) {
+            return false;
+        }
+        Byte marker = metadata.getPersistentDataContainer().get(
+            identityKey,
+            PersistentDataType.BYTE
+        );
+        return marker != null && marker == AUTHENTIC_MARKER;
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/SortingStickListener.java

@@ -0,0 +1,66 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.Objects;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.block.Barrel;
+import org.bukkit.block.Block;
+import org.bukkit.block.Chest;
+import org.bukkit.block.Container;
+import org.bukkit.block.Lockable;
+import org.bukkit.entity.Player;
+import org.bukkit.event.EventHandler;
+import org.bukkit.event.EventPriority;
+import org.bukkit.event.Listener;
+import org.bukkit.event.block.Action;
+import org.bukkit.event.player.PlayerInteractEvent;
+import org.bukkit.inventory.EquipmentSlot;
+
+public final class SortingStickListener implements Listener {
+    private final SortingStickItemFactory sticks;
+    private final InventorySortingService sorting;
+
+    public SortingStickListener(
+        SortingStickItemFactory sticks,
+        InventorySortingService sorting
+    ) {
+        this.sticks = Objects.requireNonNull(sticks, "sticks");
+        this.sorting = Objects.requireNonNull(sorting, "sorting");
+    }
+
+    @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
+    public void onInteract(PlayerInteractEvent event) {
+        if (event.isCancelled()
+            || event.getHand() != EquipmentSlot.HAND
+            || !isRightClick(event.getAction())
+            || !sticks.isSortingStick(event.getItem())) {
+            return;
+        }
+
+        event.setCancelled(true);
+        Player player = event.getPlayer();
+        Block clicked = event.getClickedBlock();
+        if (clicked != null) {
+            Object state = clicked.getState();
+            if (state instanceof Chest || state instanceof Barrel) {
+                if (((Lockable) state).isLocked()) {
+                    player.sendActionBar(Component.text(
+                        "That container is locked.",
+                        NamedTextColor.RED
+                    ));
+                    return;
+                }
+                sorting.sortContainer(((Container) state).getInventory());
+                player.sendActionBar(Component.text("Container sorted.", NamedTextColor.GREEN));
+                return;
+            }
+        }
+
+        sorting.sortPlayerMainStorage(player.getInventory());
+        player.sendActionBar(Component.text("Inventory sorted.", NamedTextColor.GREEN));
+    }
+
+    private static boolean isRightClick(Action action) {
+        return action == Action.RIGHT_CLICK_AIR || action == Action.RIGHT_CLICK_BLOCK;
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/SortingStickRecipeRegistrar.java

@@ -0,0 +1,66 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.List;
+import java.util.Objects;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.Server;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.ShapedRecipe;
+
+public final class SortingStickRecipeRegistrar {
+    private final NamespacedKey recipeKey;
+    private final SortingStickItemFactory itemFactory;
+    private final SortingStickRecipeSpec recipeSpec;
+    private final RecipeFactory recipeFactory;
+
+    public SortingStickRecipeRegistrar(
+        NamespacedKey recipeKey,
+        SortingStickItemFactory itemFactory,
+        SortingStickRecipeSpec recipeSpec
+    ) {
+        this(recipeKey, itemFactory, recipeSpec, ShapedRecipe::new);
+    }
+
+    SortingStickRecipeRegistrar(
+        NamespacedKey recipeKey,
+        SortingStickItemFactory itemFactory,
+        SortingStickRecipeSpec recipeSpec,
+        RecipeFactory recipeFactory
+    ) {
+        this.recipeKey = Objects.requireNonNull(recipeKey, "recipeKey");
+        this.itemFactory = Objects.requireNonNull(itemFactory, "itemFactory");
+        this.recipeSpec = Objects.requireNonNull(recipeSpec, "recipeSpec");
+        this.recipeFactory = Objects.requireNonNull(recipeFactory, "recipeFactory");
+    }
+
+    public boolean register(Server server) {
+        Objects.requireNonNull(server, "server");
+        boolean registered = true;
+        for (Material storage : List.of(Material.CHEST, Material.BARREL)) {
+            ShapedRecipe recipe = createRecipe(storage);
+            registered = server.addRecipe(recipe) && registered;
+        }
+        return registered;
+    }
+
+    private ShapedRecipe createRecipe(Material storage) {
+        ItemStack result = itemFactory.create();
+        result.setAmount(recipeSpec.outputAmount());
+        NamespacedKey variantKey = new NamespacedKey(
+            recipeKey.getNamespace(),
+            recipeKey.getKey() + "_" + storage.name().toLowerCase(java.util.Locale.ROOT)
+        );
+        ShapedRecipe recipe = recipeFactory.create(variantKey, result);
+        recipe.shape(recipeSpec.shape().toArray(String[]::new));
+        recipe.setIngredient('C', storage);
+        recipe.setIngredient('R', Material.REDSTONE);
+        recipe.setIngredient('S', Material.STICK);
+        return recipe;
+    }
+
+    @FunctionalInterface
+    interface RecipeFactory {
+        ShapedRecipe create(NamespacedKey key, ItemStack result);
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/SortingStickRecipeSpec.java

@@ -0,0 +1,29 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import org.bukkit.Material;
+
+public record SortingStickRecipeSpec(
+    List<String> shape,
+    Map<Character, Set<Material>> ingredients,
+    int outputAmount
+) {
+    public SortingStickRecipeSpec {
+        shape = List.copyOf(shape);
+        ingredients = Map.copyOf(ingredients);
+    }
+
+    public static SortingStickRecipeSpec defaultRecipe() {
+        return new SortingStickRecipeSpec(
+            List.of(" C ", " R ", " S "),
+            Map.of(
+                'C', Set.of(Material.CHEST, Material.BARREL),
+                'R', Set.of(Material.REDSTONE),
+                'S', Set.of(Material.STICK)
+            ),
+            1
+        );
+    }
+}

src/main/java/games/dmg/spigotinventoryhelper/SpigotInventoryHelperPlugin.java

@@ -1,10 +1,38 @@
 package games.dmg.spigotinventoryhelper;
 
+import org.bukkit.NamespacedKey;
 import org.bukkit.plugin.java.JavaPlugin;
 
 public final class SpigotInventoryHelperPlugin extends JavaPlugin {
+    private SortingStickItemFactory sortingSticks;
+
     @Override
     public void onEnable() {
+        sortingSticks = new SortingStickItemFactory(new NamespacedKey(this, "sorting_stick"));
+        SortingStickRecipeRegistrar recipes = new SortingStickRecipeRegistrar(
+            new NamespacedKey(this, "sorting_stick_recipe"),
+            sortingSticks,
+            SortingStickRecipeSpec.defaultRecipe()
+        );
+        if (!recipes.register(getServer())) {
+            getLogger().warning("One or more Sorting Stick recipes could not be registered.");
+        }
+        InventorySortingService sorting = new InventorySortingService(new InventorySorter());
+        getServer().getPluginManager().registerEvents(
+            new SortingStickListener(sortingSticks, sorting),
+            this
+        );
+        getServer().getPluginManager().registerEvents(
+            new BrokenToolListener(this, new ToolReplacementService()),
+            this
+        );
         getLogger().info("Spigot Inventory Helper enabled.");
     }
+
+    SortingStickItemFactory sortingSticks() {
+        if (sortingSticks == null) {
+            throw new IllegalStateException("Sorting Stick service is unavailable");
+        }
+        return sortingSticks;
+    }
 }

src/main/java/games/dmg/spigotinventoryhelper/ToolReplacementService.java

@@ -0,0 +1,61 @@
+package games.dmg.spigotinventoryhelper;
+
+import java.util.Objects;
+import org.bukkit.Material;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+
+public final class ToolReplacementService {
+    private static final int HOTBAR_SIZE = 9;
+    private static final int PLAYER_STORAGE_SIZE = 36;
+
+    public boolean replace(
+        PlayerInventory inventory,
+        Material brokenMaterial,
+        int selectedSlot
+    ) {
+        Objects.requireNonNull(inventory, "inventory");
+        Objects.requireNonNull(brokenMaterial, "brokenMaterial");
+        if (selectedSlot < 0 || selectedSlot >= HOTBAR_SIZE || !isEmpty(inventory.getItem(selectedSlot))) {
+            return false;
+        }
+
+        ItemStack[] storage = inventory.getStorageContents();
+        int source = find(storage, brokenMaterial, HOTBAR_SIZE, PLAYER_STORAGE_SIZE, selectedSlot);
+        if (source < 0) {
+            source = find(storage, brokenMaterial, 0, HOTBAR_SIZE, selectedSlot);
+        }
+        if (source < 0) {
+            return false;
+        }
+
+        ItemStack replacement = storage[source];
+        inventory.setItem(selectedSlot, replacement);
+        inventory.setItem(source, null);
+        return true;
+    }
+
+    private static int find(
+        ItemStack[] storage,
+        Material material,
+        int from,
+        int to,
+        int excludedSlot
+    ) {
+        int limit = Math.min(to, storage.length);
+        for (int slot = from; slot < limit; slot++) {
+            ItemStack candidate = storage[slot];
+            if (slot != excludedSlot
+                && candidate != null
+                && candidate.getAmount() > 0
+                && candidate.getType() == material) {
+                return slot;
+            }
+        }
+        return -1;
+    }
+
+    private static boolean isEmpty(ItemStack item) {
+        return item == null || item.getType() == Material.AIR || item.getAmount() == 0;
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/BrokenToolListenerTest.java

@@ -0,0 +1,59 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import java.util.concurrent.atomic.AtomicReference;
+import org.bukkit.Material;
+import org.bukkit.entity.Player;
+import org.bukkit.event.player.PlayerItemBreakEvent;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.junit.jupiter.api.Test;
+
+final class BrokenToolListenerTest {
+    @Test
+    void replacesAMainHandToolOnTheNextServerTick() {
+        ToolReplacementService replacements = mock(ToolReplacementService.class);
+        AtomicReference<Runnable> scheduled = new AtomicReference<>();
+        BrokenToolListener listener = new BrokenToolListener(replacements, scheduled::set);
+        PlayerItemBreakEvent event = mock(PlayerItemBreakEvent.class);
+        Player player = mock(Player.class);
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack broken = mock(ItemStack.class);
+        when(event.getPlayer()).thenReturn(player);
+        when(event.getBrokenItem()).thenReturn(broken);
+        when(player.getInventory()).thenReturn(inventory);
+        when(inventory.getItemInMainHand()).thenReturn(broken);
+        when(inventory.getHeldItemSlot()).thenReturn(3);
+        when(broken.getType()).thenReturn(Material.DIAMOND_PICKAXE);
+
+        listener.onItemBreak(event);
+        scheduled.get().run();
+
+        verify(replacements).replace(inventory, Material.DIAMOND_PICKAXE, 3);
+    }
+
+    @Test
+    void ignoresAnOffHandToolBreak() {
+        ToolReplacementService replacements = mock(ToolReplacementService.class);
+        AtomicReference<Runnable> scheduled = new AtomicReference<>();
+        BrokenToolListener listener = new BrokenToolListener(replacements, scheduled::set);
+        PlayerItemBreakEvent event = mock(PlayerItemBreakEvent.class);
+        Player player = mock(Player.class);
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack mainHand = mock(ItemStack.class);
+        ItemStack brokenOffHand = mock(ItemStack.class);
+        when(event.getPlayer()).thenReturn(player);
+        when(event.getBrokenItem()).thenReturn(brokenOffHand);
+        when(player.getInventory()).thenReturn(inventory);
+        when(inventory.getItemInMainHand()).thenReturn(mainHand);
+
+        listener.onItemBreak(event);
+
+        verifyNoInteractions(replacements);
+        org.junit.jupiter.api.Assertions.assertNull(scheduled.get());
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/InventorySorterTest.java

@@ -0,0 +1,89 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.assertAll;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import java.util.concurrent.atomic.AtomicInteger;
+import org.bukkit.Material;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.ItemMeta;
+import org.junit.jupiter.api.Test;
+
+final class InventorySorterTest {
+    @Test
+    void consolidatesStacksAndOrdersMaterialsAlphabetically() {
+        ItemStack[] contents = {
+            stack(Material.STONE, 5),
+            stack(Material.DIRT, 40),
+            stack(Material.DIRT, 30),
+            null
+        };
+
+        ItemStack[] sorted = new InventorySorter().sort(contents);
+
+        assertAll(
+            () -> assertEquals(Material.DIRT, sorted[0].getType()),
+            () -> assertEquals(64, sorted[0].getAmount()),
+            () -> assertEquals(Material.DIRT, sorted[1].getType()),
+            () -> assertEquals(6, sorted[1].getAmount()),
+            () -> assertEquals(Material.STONE, sorted[2].getType()),
+            () -> assertEquals(5, sorted[2].getAmount()),
+            () -> assertNull(sorted[3])
+        );
+    }
+
+    @Test
+    void preservesMetadataAndStableOrderForDissimilarVariants() {
+        ItemMeta named = mock(ItemMeta.class, "named");
+        ItemMeta enchanted = mock(ItemMeta.class, "enchanted");
+        ItemStack[] contents = {
+            stack(Material.STONE, 5, named),
+            stack(Material.STONE, 2, enchanted),
+            stack(Material.STONE, 4, named)
+        };
+
+        ItemStack[] sorted = new InventorySorter().sort(contents);
+
+        assertAll(
+            () -> assertSame(named, sorted[0].getItemMeta()),
+            () -> assertEquals(9, sorted[0].getAmount()),
+            () -> assertSame(enchanted, sorted[1].getItemMeta()),
+            () -> assertEquals(2, sorted[1].getAmount()),
+            () -> assertNull(sorted[2])
+        );
+    }
+
+    private static ItemStack stack(Material material, int initialAmount) {
+        return stack(material, initialAmount, null);
+    }
+
+    private static ItemStack stack(
+        Material material,
+        int initialAmount,
+        ItemMeta metadata
+    ) {
+        AtomicInteger amount = new AtomicInteger(initialAmount);
+        ItemStack item = mock(ItemStack.class);
+        when(item.getType()).thenReturn(material);
+        when(item.getAmount()).thenAnswer(ignored -> amount.get());
+        when(item.getItemMeta()).thenReturn(metadata);
+        doAnswer(invocation -> {
+            amount.set(invocation.getArgument(0));
+            return null;
+        }).when(item).setAmount(anyInt());
+        when(item.getMaxStackSize()).thenReturn(64);
+        when(item.isSimilar(any(ItemStack.class))).thenAnswer(invocation -> {
+            ItemStack other = invocation.getArgument(0);
+            return other.getType() == material && other.getItemMeta() == metadata;
+        });
+        when(item.clone()).thenAnswer(ignored -> stack(material, amount.get(), metadata));
+        return item;
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/InventorySortingServiceTest.java

@@ -0,0 +1,44 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.Arrays;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+final class InventorySortingServiceTest {
+    @Test
+    void sortsOnlyPlayerMainStorageSlots() {
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        InventorySorter sorter = mock(InventorySorter.class);
+        ItemStack[] storage = stacks(36);
+        ItemStack[] mainStorage = Arrays.copyOfRange(storage, 9, 36);
+        ItemStack[] sortedMain = mainStorage.clone();
+        ItemStack first = sortedMain[0];
+        sortedMain[0] = sortedMain[26];
+        sortedMain[26] = first;
+        when(inventory.getStorageContents()).thenReturn(storage);
+        when(sorter.sort(mainStorage)).thenReturn(sortedMain);
+
+        new InventorySortingService(sorter).sortPlayerMainStorage(inventory);
+
+        ArgumentCaptor<ItemStack[]> result = ArgumentCaptor.forClass(ItemStack[].class);
+        verify(inventory).setStorageContents(result.capture());
+        assertArrayEquals(Arrays.copyOfRange(storage, 0, 9),
+            Arrays.copyOfRange(result.getValue(), 0, 9));
+        assertArrayEquals(sortedMain, Arrays.copyOfRange(result.getValue(), 9, 36));
+    }
+
+    private static ItemStack[] stacks(int size) {
+        ItemStack[] stacks = new ItemStack[size];
+        for (int slot = 0; slot < size; slot++) {
+            stacks[slot] = mock(ItemStack.class, "slot-" + slot);
+        }
+        return stacks;
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/SortingStickItemFactoryTest.java

@@ -0,0 +1,74 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.ItemMeta;
+import org.bukkit.persistence.PersistentDataContainer;
+import org.bukkit.persistence.PersistentDataType;
+import org.junit.jupiter.api.Test;
+
+final class SortingStickItemFactoryTest {
+    @Test
+    void createsOneDistinctMetadataAuthenticatedStick() {
+        NamespacedKey key = new NamespacedKey("test", "sorting_stick");
+        ItemStack item = mock(ItemStack.class);
+        ItemMeta metadata = mock(ItemMeta.class);
+        PersistentDataContainer data = mock(PersistentDataContainer.class);
+        when(item.getItemMeta()).thenReturn(metadata);
+        when(metadata.getPersistentDataContainer()).thenReturn(data);
+
+        SortingStickItemFactory factory = new SortingStickItemFactory(key, () -> item);
+
+        assertSame(item, factory.create());
+        verify(item).setAmount(1);
+        verify(metadata).displayName(Component.text("Sorting Stick", NamedTextColor.GOLD));
+        verify(metadata).setEnchantmentGlintOverride(true);
+        verify(data).set(key, PersistentDataType.BYTE, (byte) 1);
+        verify(item).setItemMeta(metadata);
+        verify(item).getItemMeta();
+        verify(item).setType(Material.STICK);
+    }
+
+    @Test
+    void rejectsARegularRenamedStickWithoutPersistentIdentity() {
+        NamespacedKey key = new NamespacedKey("test", "sorting_stick");
+        ItemStack item = mock(ItemStack.class);
+        ItemMeta metadata = mock(ItemMeta.class);
+        PersistentDataContainer data = mock(PersistentDataContainer.class);
+        when(item.getType()).thenReturn(Material.STICK);
+        when(item.hasItemMeta()).thenReturn(true);
+        when(item.getItemMeta()).thenReturn(metadata);
+        when(metadata.getPersistentDataContainer()).thenReturn(data);
+
+        SortingStickItemFactory factory = new SortingStickItemFactory(key, () -> item);
+
+        assertFalse(factory.isSortingStick(item));
+    }
+
+    @Test
+    void acceptsAStickWithTheAuthenticPersistentMarker() {
+        NamespacedKey key = new NamespacedKey("test", "sorting_stick");
+        ItemStack item = mock(ItemStack.class);
+        ItemMeta metadata = mock(ItemMeta.class);
+        PersistentDataContainer data = mock(PersistentDataContainer.class);
+        when(item.getType()).thenReturn(Material.STICK);
+        when(item.hasItemMeta()).thenReturn(true);
+        when(item.getItemMeta()).thenReturn(metadata);
+        when(metadata.getPersistentDataContainer()).thenReturn(data);
+        when(data.get(key, PersistentDataType.BYTE)).thenReturn((byte) 1);
+
+        SortingStickItemFactory factory = new SortingStickItemFactory(key, () -> item);
+
+        assertTrue(factory.isSortingStick(item));
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/SortingStickListenerTest.java

@@ -0,0 +1,173 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import org.bukkit.block.Barrel;
+import org.bukkit.block.Block;
+import org.bukkit.block.Chest;
+import org.bukkit.entity.Player;
+import org.bukkit.event.block.Action;
+import org.bukkit.event.player.PlayerInteractEvent;
+import org.bukkit.inventory.DoubleChestInventory;
+import org.bukkit.inventory.EquipmentSlot;
+import org.bukkit.inventory.Inventory;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.junit.jupiter.api.Test;
+
+final class SortingStickListenerTest {
+    @Test
+    void sortsAChestWithoutOpeningIt() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        Player player = mock(Player.class);
+        ItemStack stick = mock(ItemStack.class);
+        Block block = mock(Block.class);
+        Chest chest = mock(Chest.class);
+        Inventory inventory = mock(Inventory.class);
+        when(event.getHand()).thenReturn(EquipmentSlot.HAND);
+        when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
+        when(event.getItem()).thenReturn(stick);
+        when(event.getPlayer()).thenReturn(player);
+        when(event.getClickedBlock()).thenReturn(block);
+        when(block.getState()).thenReturn(chest);
+        when(chest.getInventory()).thenReturn(inventory);
+        when(sticks.isSortingStick(stick)).thenReturn(true);
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verify(sorting).sortContainer(inventory);
+        verify(event).setCancelled(true);
+    }
+
+    @Test
+    void sortsABarrelWithoutOpeningIt() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        ItemStack stick = mock(ItemStack.class);
+        Block block = mock(Block.class);
+        Barrel barrel = mock(Barrel.class);
+        Inventory inventory = mock(Inventory.class);
+        when(event.getHand()).thenReturn(EquipmentSlot.HAND);
+        when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
+        when(event.getItem()).thenReturn(stick);
+        when(event.getPlayer()).thenReturn(mock(Player.class));
+        when(event.getClickedBlock()).thenReturn(block);
+        when(block.getState()).thenReturn(barrel);
+        when(barrel.getInventory()).thenReturn(inventory);
+        when(sticks.isSortingStick(stick)).thenReturn(true);
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verify(sorting).sortContainer(inventory);
+        verify(event).setCancelled(true);
+    }
+
+    @Test
+    void refusesToSortALockedContainer() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        ItemStack stick = mock(ItemStack.class);
+        Block block = mock(Block.class);
+        Chest chest = mock(Chest.class);
+        when(event.getHand()).thenReturn(EquipmentSlot.HAND);
+        when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
+        when(event.getItem()).thenReturn(stick);
+        when(event.getPlayer()).thenReturn(mock(Player.class));
+        when(event.getClickedBlock()).thenReturn(block);
+        when(block.getState()).thenReturn(chest);
+        when(chest.isLocked()).thenReturn(true);
+        when(sticks.isSortingStick(stick)).thenReturn(true);
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verifyNoInteractions(sorting);
+        verify(event).setCancelled(true);
+    }
+
+    @Test
+    void sortsTheCombinedInventoryReturnedByEitherHalfOfADoubleChest() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = authenticBlockInteraction(sticks);
+        Block block = event.getClickedBlock();
+        Chest chest = mock(Chest.class);
+        DoubleChestInventory combined = mock(DoubleChestInventory.class);
+        when(block.getState()).thenReturn(chest);
+        when(chest.getInventory()).thenReturn(combined);
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verify(sorting).sortContainer(combined);
+    }
+
+    @Test
+    void rightClickingAirSortsOnlyThePlayerMainStorage() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        Player player = mock(Player.class);
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack stick = mock(ItemStack.class);
+        when(event.getHand()).thenReturn(EquipmentSlot.HAND);
+        when(event.getAction()).thenReturn(Action.RIGHT_CLICK_AIR);
+        when(event.getItem()).thenReturn(stick);
+        when(event.getPlayer()).thenReturn(player);
+        when(player.getInventory()).thenReturn(inventory);
+        when(sticks.isSortingStick(stick)).thenReturn(true);
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verify(sorting).sortPlayerMainStorage(inventory);
+        verify(event).setCancelled(true);
+    }
+
+    @Test
+    void respectsAnInteractionCancelledByAnotherPlugin() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        when(event.isCancelled()).thenReturn(true);
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verifyNoInteractions(sticks, sorting);
+        verify(event, never()).setCancelled(true);
+    }
+
+    @Test
+    void ignoresAnOrdinaryStick() {
+        SortingStickItemFactory sticks = mock(SortingStickItemFactory.class);
+        InventorySortingService sorting = mock(InventorySortingService.class);
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        when(event.getHand()).thenReturn(EquipmentSlot.HAND);
+        when(event.getAction()).thenReturn(Action.RIGHT_CLICK_AIR);
+        when(event.getItem()).thenReturn(mock(ItemStack.class));
+
+        new SortingStickListener(sticks, sorting).onInteract(event);
+
+        verifyNoInteractions(sorting);
+        verify(event, never()).setCancelled(true);
+    }
+
+    private static PlayerInteractEvent authenticBlockInteraction(
+        SortingStickItemFactory sticks
+    ) {
+        PlayerInteractEvent event = mock(PlayerInteractEvent.class);
+        ItemStack stick = mock(ItemStack.class);
+        when(event.getHand()).thenReturn(EquipmentSlot.HAND);
+        when(event.getAction()).thenReturn(Action.RIGHT_CLICK_BLOCK);
+        when(event.getItem()).thenReturn(stick);
+        when(event.getPlayer()).thenReturn(mock(Player.class));
+        when(event.getClickedBlock()).thenReturn(mock(Block.class));
+        when(sticks.isSortingStick(stick)).thenReturn(true);
+        return event;
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/SortingStickRecipeRegistrarTest.java

@@ -0,0 +1,62 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.Server;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.ShapedRecipe;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+final class SortingStickRecipeRegistrarTest {
+    @Test
+    void registersChestAndBarrelVariants() {
+        Server server = mock(Server.class);
+        SortingStickItemFactory items = mock(SortingStickItemFactory.class);
+        ItemStack result = mock(ItemStack.class);
+        ShapedRecipe chestRecipe = mock(ShapedRecipe.class);
+        ShapedRecipe barrelRecipe = mock(ShapedRecipe.class);
+        SortingStickRecipeRegistrar.RecipeFactory recipes =
+            mock(SortingStickRecipeRegistrar.RecipeFactory.class);
+        when(items.create()).thenReturn(result);
+        when(recipes.create(any(NamespacedKey.class), any(ItemStack.class)))
+            .thenReturn(chestRecipe, barrelRecipe);
+        when(server.addRecipe(chestRecipe)).thenReturn(true);
+        when(server.addRecipe(barrelRecipe)).thenReturn(true);
+        SortingStickRecipeRegistrar registrar = new SortingStickRecipeRegistrar(
+            new NamespacedKey("test", "sorting_stick_recipe"),
+            items,
+            SortingStickRecipeSpec.defaultRecipe(),
+            recipes
+        );
+
+        assertTrue(registrar.register(server));
+        verify(chestRecipe).shape(" C ", " R ", " S ");
+        verify(chestRecipe).setIngredient('C', Material.CHEST);
+        verify(chestRecipe).setIngredient('R', Material.REDSTONE);
+        verify(chestRecipe).setIngredient('S', Material.STICK);
+        verify(barrelRecipe).shape(" C ", " R ", " S ");
+        verify(barrelRecipe).setIngredient('C', Material.BARREL);
+        verify(barrelRecipe).setIngredient('R', Material.REDSTONE);
+        verify(barrelRecipe).setIngredient('S', Material.STICK);
+        verify(server).addRecipe(chestRecipe);
+        verify(server).addRecipe(barrelRecipe);
+        verify(result, times(2)).setAmount(1);
+
+        ArgumentCaptor<NamespacedKey> keys = ArgumentCaptor.forClass(NamespacedKey.class);
+        verify(recipes, times(2)).create(keys.capture(), any(ItemStack.class));
+        assertEquals(
+            List.of("sorting_stick_recipe_chest", "sorting_stick_recipe_barrel"),
+            keys.getAllValues().stream().map(NamespacedKey::getKey).toList()
+        );
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/SortingStickRecipeSpecTest.java

@@ -0,0 +1,21 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.List;
+import java.util.Set;
+import org.bukkit.Material;
+import org.junit.jupiter.api.Test;
+
+final class SortingStickRecipeSpecTest {
+    @Test
+    void definesBothStorageVariantsInTheCenterColumn() {
+        SortingStickRecipeSpec recipe = SortingStickRecipeSpec.defaultRecipe();
+
+        assertEquals(List.of(" C ", " R ", " S "), recipe.shape());
+        assertEquals(Set.of(Material.CHEST, Material.BARREL), recipe.ingredients().get('C'));
+        assertEquals(Set.of(Material.REDSTONE), recipe.ingredients().get('R'));
+        assertEquals(Set.of(Material.STICK), recipe.ingredients().get('S'));
+        assertEquals(1, recipe.outputAmount());
+    }
+}

src/test/java/games/dmg/spigotinventoryhelper/ToolReplacementServiceTest.java

@@ -0,0 +1,91 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import org.bukkit.Material;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.junit.jupiter.api.Test;
+
+final class ToolReplacementServiceTest {
+    @Test
+    void movesAnExactMainStorageReplacementIntoTheBrokenSlot() {
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack[] storage = new ItemStack[36];
+        ItemStack hotbarCandidate = tool(Material.DIAMOND_PICKAXE);
+        ItemStack mainCandidate = tool(Material.DIAMOND_PICKAXE);
+        storage[1] = hotbarCandidate;
+        storage[10] = mainCandidate;
+        when(inventory.getStorageContents()).thenReturn(storage);
+
+        boolean replaced = new ToolReplacementService().replace(
+            inventory,
+            Material.DIAMOND_PICKAXE,
+            0
+        );
+
+        assertTrue(replaced);
+        verify(inventory).setItem(0, mainCandidate);
+        verify(inventory).setItem(10, null);
+        verify(inventory, never()).setItem(1, null);
+    }
+
+    @Test
+    void fallsBackToAnotherHotbarSlot() {
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack[] storage = new ItemStack[36];
+        ItemStack replacement = tool(Material.IRON_AXE);
+        storage[7] = replacement;
+        when(inventory.getStorageContents()).thenReturn(storage);
+
+        assertTrue(new ToolReplacementService().replace(
+            inventory,
+            Material.IRON_AXE,
+            2
+        ));
+        verify(inventory).setItem(2, replacement);
+        verify(inventory).setItem(7, null);
+    }
+
+    @Test
+    void leavesInventoryUnchangedWithoutAnExactMaterialMatch() {
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack[] storage = new ItemStack[36];
+        storage[10] = tool(Material.IRON_PICKAXE);
+        when(inventory.getStorageContents()).thenReturn(storage);
+
+        assertFalse(new ToolReplacementService().replace(
+            inventory,
+            Material.DIAMOND_PICKAXE,
+            0
+        ));
+        verify(inventory, never()).setItem(0, storage[10]);
+        verify(inventory, never()).setItem(10, null);
+    }
+
+    @Test
+    void doesNotOverwriteAnItemPlacedIntoTheBrokenSlot() {
+        PlayerInventory inventory = mock(PlayerInventory.class);
+        ItemStack occupied = tool(Material.COBBLESTONE);
+        when(inventory.getItem(0)).thenReturn(occupied);
+
+        assertFalse(new ToolReplacementService().replace(
+            inventory,
+            Material.DIAMOND_PICKAXE,
+            0
+        ));
+        verify(inventory, never()).getStorageContents();
+    }
+
+    private static ItemStack tool(Material material) {
+        ItemStack item = mock(ItemStack.class);
+        when(item.getType()).thenReturn(material);
+        when(item.getAmount()).thenReturn(1);
+        return item;
+    }
+}