From bf7f01a39eb143bb5f0c1e4d82e50ed80f4427c3 Mon Sep 17 00:00:00 2001 From: Dylan Garvis Date: Wed, 9 Sep 2026 23:18:25 -0400 Subject: [PATCH] chore(knowledge): move canonical docs to shared SoMC wiki --- AGENTS.md | 41 +----- README.md | 2 +- knowledge/index.md | 17 --- knowledge/log.md | 135 ------------------ knowledge/user-stories/index.md | 21 --- .../us-001-build-and-release-plugin.md | 28 ---- ...-002-create-and-use-shared-quest-boards.md | 27 ---- .../us-003-create-a-block-delivery-quest.md | 32 ----- .../us-004-browse-available-quests.md | 29 ---- ...005-deliver-blocks-and-complete-a-quest.md | 32 ----- .../us-006-cancel-an-owned-quest.md | 27 ---- ...-007-expire-quests-and-claim-held-items.md | 34 ----- .../us-008-control-player-quest-commands.md | 28 ---- ...-a-screen-fitting-quest-board-interface.md | 30 ---- .../us-010-generate-a-physical-quest-board.md | 29 ---- ...011-add-readable-physical-board-signage.md | 28 ---- .../us-012-create-quests-near-a-board.md | 29 ---- .../us-013-show-custom-reward-item-names.md | 26 ---- 18 files changed, 6 insertions(+), 589 deletions(-) delete mode 100644 knowledge/index.md delete mode 100644 knowledge/log.md delete mode 100644 knowledge/user-stories/index.md delete mode 100644 knowledge/user-stories/us-001-build-and-release-plugin.md delete mode 100644 knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md delete mode 100644 knowledge/user-stories/us-003-create-a-block-delivery-quest.md delete mode 100644 knowledge/user-stories/us-004-browse-available-quests.md delete mode 100644 knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md delete mode 100644 knowledge/user-stories/us-006-cancel-an-owned-quest.md delete mode 100644 knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md delete mode 100644 knowledge/user-stories/us-008-control-player-quest-commands.md delete mode 100644 knowledge/user-stories/us-009-use-a-screen-fitting-quest-board-interface.md delete mode 100644 knowledge/user-stories/us-010-generate-a-physical-quest-board.md delete mode 100644 knowledge/user-stories/us-011-add-readable-physical-board-signage.md delete mode 100644 knowledge/user-stories/us-012-create-quests-near-a-board.md delete mode 100644 knowledge/user-stories/us-013-show-custom-reward-item-names.md diff --git a/AGENTS.md b/AGENTS.md index f17ae4a..f8a11dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,40 +1,9 @@ -# Spigot Quest Board Agent Guide +# spigot-quest-board agent entrypoint -## Project +The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md). -Spigot Quest Board is a Java 25 plugin for Purpur 26.2. It provides shared physical quest boards where players escrow rewards, deliver requested block items, and claim delivered or returned items. +Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-quest-board/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-quest-board/` stories. Also follow the parent workspace `AGENTS.md` when present. -## Canonical knowledge +For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-quest-board/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access. -- `knowledge/` is the canonical OKF v0.1 knowledge bundle. -- Read `knowledge/index.md` and the relevant documents in `knowledge/user-stories/` before changing behavior. -- Every feature or behavior change requires an approved user story with task-list acceptance criteria. -- Preserve unknown YAML frontmatter fields when editing knowledge documents. -- Keep `knowledge/index.md`, `knowledge/log.md`, and `knowledge/user-stories/index.md` current. - -## Development - -- Compile against the Purpur API version declared in `build.gradle.kts`. -- Use Java 25 and enable strict compiler linting. -- Prefer small, server-independent domain objects and services that can be unit tested. -- Use test-driven development where practical: add a failing test, implement the minimum behavior, then refactor. -- Treat escrow, completion, cancellation, expiry, and claiming as atomic state transitions. Never duplicate or silently discard player items. -- Key players by UUID, not display name. -- Persist board, quest, escrow, and claim state safely across restarts using atomic file replacement where supported. -- Use UTC and RFC 3339 timestamps for persisted or documented date-times. -- Keep player-facing command autocomplete permission-aware and context-sensitive. -- Use Purpur's supported Paper dialog API for native dialog interfaces. - -## Verification - -Run before completing a story: - -```bash -./gradlew clean check jar -``` - -Mark acceptance criteria complete only after implementation and verification. - -## Git - -Use conventional commits in the form `type(scope): description`, with summaries under 72 characters. +Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push. diff --git a/README.md b/README.md index 77a0990..d7986ea 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A Purpur 26.2 plugin for shared physical quest boards. Players can escrow rewards for requested items, deliver those items at any quest board, and claim delivered or returned items safely. -The approved behavior is specified in the [OKF knowledge bundle](knowledge/index.md). +The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-quest-board/index.md). ## Status diff --git a/knowledge/index.md b/knowledge/index.md deleted file mode 100644 index bd66897..0000000 --- a/knowledge/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -type: Index -title: Spigot Quest Board Knowledge -description: Entry point for the Spigot Quest Board OKF knowledge bundle. -okf_version: "0.1" ---- - -# Spigot Quest Board Knowledge - -This bundle specifies shared physical quest boards, reward escrow, item deliveries, item claims, player commands, administration, persistence, and plugin delivery requirements. - -Login guidance is covered by [quest browsing](user-stories/us-004-browse-available-quests.md) and [recurring pending-item reminders](user-stories/us-007-expire-quests-and-claim-held-items.md). - -## Explore - -- [User stories](user-stories/index.md) -- [Knowledge log](log.md) diff --git a/knowledge/log.md b/knowledge/log.md deleted file mode 100644 index 7fc43ab..0000000 --- a/knowledge/log.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -type: Log -title: Spigot Quest Board Knowledge Log -description: Chronological record of material decisions affecting Spigot Quest Board. ---- - -# Spigot Quest Board Knowledge Log - -## 2026-09-10T01:38:21Z — Inventory-item quest requests - -- Extended [US-003](user-stories/us-003-create-a-block-delivery-quest.md) and [US-005](user-stories/us-005-deliver-blocks-and-complete-a-quest.md) to support inventory item materials, including shulker shells, rather than only blocks. -- Validation and autocomplete use item eligibility and reject air and non-item materials; command, dialog, notification, and claim wording now describes items. -- Preserved the persistence format and existing escrow, delivery, and claim transitions. -- Confirmed catalog regressions failed before the fix using mocked server material properties, then verified shell creation, persisted settlement and claim acknowledgement, and existing regressions: all 134 tests and the plugin JAR passed `./gradlew clean check jar`. - -## 2026-09-05 — Initial quest-board design - -- Administrators create physical quest boards, and every board exposes the same global quests and claims. -- Players create quests by selecting a requested block material and quantity and escrowing reward items from their inventory. -- Completing players deliver the requested block items at a board and immediately receive the escrowed reward. -- Delivered blocks remain held by the quest system until the issuer claims them at a board. -- Cancelled and seven-day-expired quests return escrowed rewards through the same claim system rather than direct inventory delivery. -- Inventory overflow from rewards or claims is dropped at the receiving player's feet. -- Player `/quests` commands are disabled by default so administrators can require physical-board interaction. -- The board interface follows Spigot Base by using Purpur's supported native dialog API. - -## 2026-09-05 — Foundation started - -- Approved work begins with an OKF knowledge bundle, Java 25/Purpur 26.2 Gradle foundation, automated verification, and a public Gitea repository. - -## 2026-09-05 — Foundation completed - -- Published the project to the public `dmg/spigot-quest-board` Gitea repository. -- Added strict Java 25/Purpur 26.2 Gradle builds, plugin metadata, a metadata regression test, and CI/release workflows modeled on Spigot Base. -- Verified the plugin foundation and JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Shared physical quest boards - -- Added durable world-UUID and block-coordinate board registration through `/questadmin createboard`. -- Registered main-hand interactions open one shared native Purpur dialog while unregistered blocks remain untouched. -- Persistence publishes a board only after an atomic YAML save succeeds and rejects duplicate locations. -- Verified 11 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Quest creation and reward escrow - -- Added board-dialog and `/quests create ` creation using a valid block material, positive quantity, and the exact held reward stack. -- Escrow preserves full Bukkit item metadata in durable Base64-backed YAML and rolls inventory removal back if persistence fails. -- Quests receive UUID identifiers and UTC creation and seven-day expiration timestamps. -- Verified 26 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Shared quest browsing - -- Added globally shared active-quest listings to every board and to `/quests` and `/quests list`. -- Listings include requested blocks, exact reward summaries, issuer names, and boundary-safe remaining durations. -- Added persisted lifecycle status with backward-compatible active defaults and filtered stale quest IDs from contextual completion and cancellation suggestions. -- Verified 37 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Block delivery and quest completion - -- Added board actions and `/quests complete ` for exact requested-material delivery from player inventories. -- Completion serializes state transitions, holds delivered blocks in durable issuer claims, and grants exact escrowed rewards with owner-protected overflow drops. -- Added durable online and next-login issuer notifications and rollback before persistence succeeds. -- Verified 49 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Issuer quest cancellation - -- Added issuer-only board actions and `/quests cancel ` with ownership-filtered autocomplete. -- Cancellation atomically moves exact reward escrow into an issuer claim without directly changing inventory. -- Serialized cancellation against completion and retained active state when persistence fails. -- Verified 58 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Quest expiration and held-item claims - -- Added boundary-safe scheduled expiration that moves exact rewards into durable issuer claims. -- Added claim collection at every board and through `/quests claim`, distinguishing delivered blocks from cancelled or expired reward returns. -- Inventory overflow drops at the claimant's feet with ownership protection, and failed claim acknowledgement rolls inventory and drops back before retry. -- Added persisted online and next-login expiry notifications. -- Verified 73 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Administrative player-command control - -- Disabled all player `/quests` command forms and autocomplete by default while preserving equivalent physical-board actions. -- Added persistent `/questadmin commands enable|disable` control with permission-aware autocomplete and failure-safe updates. -- Kept administrative board creation available independently of the player-command setting. -- Verified 82 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Screen-fitting quest-board dialogs - -- Replaced the clipped 800-pixel combined board screen with a compact 420-pixel dashboard. -- Split browsing, creation, and claims into dedicated native dialog screens with Back navigation. -- Presented active quests as individual detail dialogs while retaining completion and issuer cancellation actions. -- Verified 88 tests, including a 250-quest navigation case, and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Generated physical quest boards - -- Added `/questadmin createboard physical` to generate a five-wide, four-tall board above the targeted ground anchor facing the administrator. -- Used oak-log pillars, an oak-plank face, and three oak wall signs with obfuscated decorative text. -- Registered all visible planks and signs in one durable operation and added obstruction checks plus block rollback when construction or persistence fails. -- Preserved existing single-block board creation and persisted board compatibility. -- Verified 103 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Readable physical-board signage - -- Added centered `Quest Board` and right-click instruction signs on the two layers above each generated board's three decorative signs. -- Registered all five signs and the plank face as shared-board interaction locations. -- Added exact legacy-structure detection and failure-safe startup upgrades for previously generated three-sign boards without touching custom or altered structures. -- Verified 111 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Glowing readable board signs - -- Enabled glowing front-side text on generated title and instruction signs while retaining non-glowing decorative signs. -- Added exact full-structure detection to refresh existing generated boards once without modifying custom or altered signs. -- Added two-sign snapshot rollback when a refresh cannot complete safely. -- Verified 116 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Nearby command-based quest creation - -- Allowed `/quests create ` and its material and quantity autocomplete within five blocks of any registered board location even while global player commands are disabled. -- Kept listing, completion, cancellation, and claiming commands disabled under that setting while preserving global command behavior when enabled. -- Enforced same-world Euclidean proximity with an inclusive five-block boundary for custom and generated boards. -- Verified 121 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-05 — Named reward identification - -- Displayed custom reward names together with their material type in shared board details and command listings, such as `1 × Shopping List (PAPER)`. -- Stored safe plain-text custom names alongside unchanged exact item metadata and inferred names from valid historical escrow data when possible. -- Kept malformed or unavailable metadata from blocking quest browsing by falling back to material descriptions. -- Verified 128 tests and the plugin JAR with `./gradlew clean check jar`. - -## 2026-09-07T01:31:27Z — Login quest guidance and recurring claim reminders - -- Extended [US-004](user-stories/us-004-browse-available-quests.md) with a private active, unexpired quest count on every login and guidance to visit the quest board to accept or create a quest. -- Extended [US-007](user-stories/us-007-expire-quests-and-claim-held-items.md) with reminders on every login while actual pending claims remain, independently of notification acknowledgement and across reloads. -- Preserved existing real-time and durable notifications without changing claim storage or collection. -- Confirmed new behavior tests failed before implementation, then verified all 130 tests and the plugin JAR with `./gradlew clean check jar`. diff --git a/knowledge/user-stories/index.md b/knowledge/user-stories/index.md deleted file mode 100644 index bd2866f..0000000 --- a/knowledge/user-stories/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -type: Index -title: Spigot Quest Board User Stories -description: Catalog of user stories for the Spigot Quest Board plugin. ---- - -# Spigot Quest Board User Stories - -1. [US-001: Build and release the plugin](us-001-build-and-release-plugin.md) -2. [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -3. [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md) -4. [US-004: Browse available quests](us-004-browse-available-quests.md) — includes login quest counts and board guidance. -5. [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) -6. [US-006: Cancel an owned quest](us-006-cancel-an-owned-quest.md) -7. [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) — includes recurring login reminders for unclaimed items. -8. [US-008: Control player quest commands](us-008-control-player-quest-commands.md) -9. [US-009: Use a screen-fitting quest-board interface](us-009-use-a-screen-fitting-quest-board-interface.md) -10. [US-010: Generate a physical quest-board structure](us-010-generate-a-physical-quest-board.md) -11. [US-011: Add readable physical-board signage](us-011-add-readable-physical-board-signage.md) -12. [US-012: Create quests by command near a board](us-012-create-quests-near-a-board.md) -13. [US-013: Show custom reward item names](us-013-show-custom-reward-item-names.md) diff --git a/knowledge/user-stories/us-001-build-and-release-plugin.md b/knowledge/user-stories/us-001-build-and-release-plugin.md deleted file mode 100644 index 0afe7bc..0000000 --- a/knowledge/user-stories/us-001-build-and-release-plugin.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -type: User Story -title: "US-001: Build and release the plugin" -description: Give maintainers repeatable Purpur builds, automated verification, and versioned public Gitea releases. -status: done ---- - -# US-001: Build and release the plugin - -As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested, correctly versioned artifacts can be distributed consistently. - -## Acceptance criteria - -- [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] Plugin metadata declares the entrypoint, player and admin commands, and permissions. -- [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] The project is published in the public `dmg/spigot-quest-board` Gitea repository. -- [x] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Quest Board names and identifiers. - -## Related - -- [User-story catalog](index.md) diff --git a/knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md b/knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md deleted file mode 100644 index bff65ed..0000000 --- a/knowledge/user-stories/us-002-create-and-use-shared-quest-boards.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -type: User Story -title: "US-002: Create and use shared quest boards" -description: Let administrators establish persistent physical boards that expose one shared quest system. -status: done ---- - -# US-002: Create and use shared quest boards - -As an **administrator**, I want to turn a targeted block into a quest board so that players can interact with quests at controlled physical locations. - -## Acceptance criteria - -- [x] An authorized administrator can use `/questadmin createboard` to register the block they are targeting. -- [x] Creation rejects a missing, invalid, or already registered target without changing state. -- [x] Registered boards persist across server restarts with their world and block coordinates. -- [x] Interacting with any registered board opens the quest-board interface. -- [x] Every registered board exposes the same global quests and claimable items. -- [x] The interface uses Purpur's supported native dialog API and follows the interaction style of Spigot Base. -- [x] Ordinary block interaction is not intercepted at unregistered locations. -- [x] Administrative actions require the `spigotquestboard.admin` permission, granted to server operators by default. -- [x] Automated tests verify board registration, persistence, shared visibility, authorization, and interaction routing. - -## Related - -- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-004: Browse available quests](us-004-browse-available-quests.md) diff --git a/knowledge/user-stories/us-003-create-a-block-delivery-quest.md b/knowledge/user-stories/us-003-create-a-block-delivery-quest.md deleted file mode 100644 index cdc6469..0000000 --- a/knowledge/user-stories/us-003-create-a-block-delivery-quest.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: User Story -title: "US-003: Create an item-delivery quest" -description: Let a player request inventory items while safely escrowing an inventory-funded reward. -status: done ---- - -# US-003: Create an item-delivery quest - -As a **player**, I want to request an item material and quantity in exchange for items I already own so that another player can fulfill my request safely. - -## Acceptance criteria - -- [x] Requests accept all inventory item materials, including shulker shells and existing block items, while rejecting air, invalid names, and non-item materials. -- [x] Contextual material autocomplete includes non-block items; command and dialog wording describes items rather than only blocks. -- [x] Regression tests verify shell creation, autocomplete, and existing block-item support. - -- [x] A player can create a quest through a registered quest board by selecting a valid item material, a positive quantity, and reward items from their inventory. -- [x] Reward items must exist in the issuer's inventory and are removed only when quest creation succeeds. -- [x] Removed rewards are held durably in escrow by the quest system. -- [x] A created quest records a unique identifier, issuer UUID and current name, requested material and quantity, exact reward items, creation time, and expiration time. -- [x] Each quest expires exactly seven days after successful creation. -- [x] Invalid input, insufficient reward items, or persistence failure leaves the issuer's inventory unchanged and creates no quest. -- [x] When player commands are enabled, `/quests create ...` provides equivalent validated creation behavior with contextual autocomplete. -- [x] Quest state and item metadata survive server restarts without duplication or loss. -- [x] Automated tests verify validation, escrow, rollback, timestamps, command routing, and persistence. - -## Related - -- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) -- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-004-browse-available-quests.md b/knowledge/user-stories/us-004-browse-available-quests.md deleted file mode 100644 index 8535b2a..0000000 --- a/knowledge/user-stories/us-004-browse-available-quests.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -type: User Story -title: "US-004: Browse available quests" -description: Let players inspect globally available quests and their essential terms. -status: done ---- - -# US-004: Browse available quests - -As a **player**, I want to browse current quests so that I can decide which block deliveries to fulfill. - -## Acceptance criteria - -- [x] Every registered board lists the same active quests. -- [x] Each listing shows the requested block material, quantity, reward, issuer, and time remaining. -- [x] Remaining durations are clear and never display an expired quest as active. -- [x] Completed, cancelled, and expired quests are excluded from the active listing. -- [x] When player commands are enabled, `/quests` and `/quests list` provide the same active quest information in chat. -- [x] Listing and autocomplete do not expose stale quest identifiers as completable or cancellable. -- [x] Automated tests verify filtering, displayed fields, duration boundaries, and command aliases. - -- [x] Every login privately reports the global active, unexpired quest count with natural zero and singular wording, followed by “Visit the quest board to accept or create a quest.” -- [x] Automated tests verify repeated login summaries, count wording, and exclusion of completed, cancelled, and expired quests. - -## Related - -- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) -- [US-013: Show custom reward item names](us-013-show-custom-reward-item-names.md) diff --git a/knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md b/knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md deleted file mode 100644 index c76e8f8..0000000 --- a/knowledge/user-stories/us-005-deliver-blocks-and-complete-a-quest.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -type: User Story -title: "US-005: Deliver items and complete a quest" -description: Let a player deliver requested items at a quest board and receive the escrowed reward. -status: done ---- - -# US-005: Deliver items and complete a quest - -As a **player**, I want to deliver requested items to a quest board so that I receive the promised reward and the issuer can claim my delivery. - -## Acceptance criteria - -- [x] Non-block requested items, including shulker shells, can be delivered and held for issuer claiming using existing escrow and rollback protections. -- [x] Delivery notifications and claim messages refer to items, and regression tests verify shell settlement and existing block deliveries. - -- [x] An active quest offers a Complete Quest action through every registered board. -- [x] Completion requires the delivering player to possess the full requested quantity of the exact item material. -- [x] Successful completion removes the requested items from the delivering player's inventory and stores them as a claim for the issuer. -- [x] Successful completion gives the exact escrowed reward items to the delivering player. -- [x] Reward items that do not fit are dropped safely at the delivering player's feet with a clear message. -- [x] The issuer is notified immediately when online or on their next login when offline that delivered items can be claimed at a quest board. -- [x] When player commands are enabled, `/quests complete ` provides equivalent behavior with contextual autocomplete. -- [x] Completion is atomic and exactly one player can complete a quest, including simultaneous attempts. -- [x] Validation or persistence failure does not consume delivered items, release rewards, or change quest state. -- [x] Completed quests are no longer shown as active or completable. -- [x] Automated tests verify inventory validation, settlement, overflow, notifications, rollback, and concurrent completion protection. - -## Related - -- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-006-cancel-an-owned-quest.md b/knowledge/user-stories/us-006-cancel-an-owned-quest.md deleted file mode 100644 index ad72868..0000000 --- a/knowledge/user-stories/us-006-cancel-an-owned-quest.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -type: User Story -title: "US-006: Cancel an owned quest" -description: Let an issuer cancel an active quest and reclaim its escrowed reward safely. -status: done ---- - -# US-006: Cancel an owned quest - -As a **quest issuer**, I want to cancel my active quest so that I can reclaim the reward when I no longer need the requested blocks. - -## Acceptance criteria - -- [x] An issuer can cancel their own active quest through any registered board. -- [x] A player cannot cancel a quest issued by another player. -- [x] Completed, cancelled, and expired quests cannot be cancelled. -- [x] Cancellation removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer. -- [x] The reward is not inserted directly into the issuer's inventory during cancellation. -- [x] When player commands are enabled, `/quests cancel ` provides equivalent behavior and only autocompletes the player's cancellable quest identifiers. -- [x] Cancellation and simultaneous completion are serialized so items cannot be duplicated or lost. -- [x] Persistence failure leaves the quest active and its reward escrowed. -- [x] Automated tests verify ownership, state validation, claim creation, autocomplete, rollback, and completion races. - -## Related - -- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md b/knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md deleted file mode 100644 index eaaebf6..0000000 --- a/knowledge/user-stories/us-007-expire-quests-and-claim-held-items.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -type: User Story -title: "US-007: Expire quests and claim held items" -description: Hold delivered blocks and returned rewards until their owner safely claims them. -status: done ---- - -# US-007: Expire quests and claim held items - -As a **quest issuer**, I want delivered blocks and returned rewards held at the shared quest board so that I can retrieve them safely. - -## Acceptance criteria - -- [x] An uncompleted quest expires seven days after its creation time. -- [x] Expiration removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer. -- [x] Completed-quest claims contain the exact block items delivered by the completing player. -- [x] Claims from completion, cancellation, and expiration can be collected through any registered board. -- [x] The board clearly distinguishes delivered blocks from returned rewards. -- [x] Online issuers receive a real-time message when items become claimable. -- [x] Offline issuers receive a message on their next login. -- [x] When player commands are enabled, `/quests claim` collects the same pending claims. -- [x] Items are inserted into the claimant's inventory where space permits; overflow is dropped safely at their feet with a clear message. -- [x] A claim is removed only after all of its items have been inserted or dropped successfully. -- [x] Pending claims and notification state survive logout and server restart without duplication or loss. -- [x] Automated tests verify expiry boundaries, each claim source, notifications, overflow, failure recovery, and persistence. - -- [x] Every login with pending claims shows “You have items waiting to be claimed. Visit the quest board to collect them.” independently of previous notification delivery. -- [x] Reminders stop once all items are claimed, preserve real-time notifications, and do not change claims or item storage. -- [x] Automated tests verify recurring reminders across logins and reloads, isolation by player, and silence after collection. - -## Related - -- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) -- [US-006: Cancel an owned quest](us-006-cancel-an-owned-quest.md) diff --git a/knowledge/user-stories/us-008-control-player-quest-commands.md b/knowledge/user-stories/us-008-control-player-quest-commands.md deleted file mode 100644 index ed1bc56..0000000 --- a/knowledge/user-stories/us-008-control-player-quest-commands.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -type: User Story -title: "US-008: Control player quest commands" -description: Let administrators require physical-board interaction by controlling access to player quest commands. -status: done ---- - -# US-008: Control player quest commands - -As an **administrator**, I want to enable or disable player quest commands so that I can require players to use physical quest boards. - -## Acceptance criteria - -- [x] Player `/quests` commands are disabled by default. -- [x] An authorized administrator can use `/questadmin commands enable|disable` with contextual autocomplete. -- [x] The command setting persists across server restarts. -- [x] When disabled, `/quests`, `list`, `complete`, `cancel`, and `claim` reject execution with a clear message directing the player to a quest board; nearby creation follows [US-012](us-012-create-quests-near-a-board.md). -- [x] Disabling commands does not prevent any equivalent action through a registered board. -- [x] `/questadmin` remains available to authorized administrators regardless of the player-command setting. -- [x] Unauthorized users cannot change the setting. -- [x] Automated tests verify the default, persistence, authorization, every gated subcommand, and autocomplete. - -## Related - -- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) -- [US-012: Create quests by command near a board](us-012-create-quests-near-a-board.md) diff --git a/knowledge/user-stories/us-009-use-a-screen-fitting-quest-board-interface.md b/knowledge/user-stories/us-009-use-a-screen-fitting-quest-board-interface.md deleted file mode 100644 index fadde34..0000000 --- a/knowledge/user-stories/us-009-use-a-screen-fitting-quest-board-interface.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -type: User Story -title: "US-009: Use a screen-fitting quest-board interface" -description: Split the oversized quest-board dialog into compact navigable screens that fit the player's display. -status: done ---- - -# US-009: Use a screen-fitting quest-board interface - -As a **player**, I want the quest-board interface to fit on screen so that I can read quest information and reach every action. - -## Acceptance criteria - -- [x] The oversized combined dialog is replaced by a compact dashboard. -- [x] Dialog message bodies use a maximum width of 420 pixels. -- [x] Browsing, quest creation, and pending claims use dedicated screens rather than one combined body. -- [x] Active quests are presented as individual navigable entries instead of one unbounded text listing. -- [x] Each quest detail shows its issuer, requested material and quantity, reward, and time remaining. -- [x] Completion, issuer-only cancellation, creation, and claim collection remain available through the board. -- [x] Nested screens provide Back controls that return toward the quest-board dashboard. -- [x] Large active-quest collections remain navigable without producing an unbounded single dialog. -- [x] Automated tests verify width limits, screen separation, navigation, displayed content, and action routing. - -## Related - -- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-004: Browse available quests](us-004-browse-available-quests.md) -- [US-005: Deliver items and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md) -- [US-007: Expire quests and claim held items](us-007-expire-quests-and-claim-held-items.md) diff --git a/knowledge/user-stories/us-010-generate-a-physical-quest-board.md b/knowledge/user-stories/us-010-generate-a-physical-quest-board.md deleted file mode 100644 index 5df4738..0000000 --- a/knowledge/user-stories/us-010-generate-a-physical-quest-board.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -type: User Story -title: "US-010: Generate a physical quest-board structure" -description: Let an administrator generate and register a decorative oak quest board at a targeted ground anchor. -status: done ---- - -# US-010: Generate a physical quest-board structure - -As an **administrator**, I want quest-board creation to optionally construct a recognizable physical board so that I do not need to build each board manually. - -## Acceptance criteria - -- [x] `/questadmin createboard physical` generates and registers a physical quest board while the existing `/questadmin createboard` behavior remains unchanged. -- [x] The targeted block is treated as the ground anchor and remains unchanged. -- [x] The generated board faces the administrator and is five blocks wide and four blocks tall. -- [x] The outer columns use oak-log pillars and the center uses oak planks. -- [x] Oak wall signs on the front display decorative obfuscated or gibberish text. -- [x] Clicking generated visible planks or signs opens the same globally shared quest-board interface. -- [x] Generation requires empty space and refuses to overwrite an existing structure. -- [x] Structure generation and interaction-location registration form one failure-safe transaction; failure restores changed blocks and registers nothing. -- [x] Generated interaction locations persist across restarts and remain compatible with existing registered boards. -- [x] The `physical` argument is offered through permission-aware command autocomplete. -- [x] Automated tests verify geometry, facing direction, obstruction handling, rollback, registration, persistence, and autocomplete. - -## Related - -- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -- [US-009: Use a screen-fitting quest-board interface](us-009-use-a-screen-fitting-quest-board-interface.md) diff --git a/knowledge/user-stories/us-011-add-readable-physical-board-signage.md b/knowledge/user-stories/us-011-add-readable-physical-board-signage.md deleted file mode 100644 index ecae79c..0000000 --- a/knowledge/user-stories/us-011-add-readable-physical-board-signage.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -type: User Story -title: "US-011: Add readable physical-board signage" -description: Give generated quest boards a readable title and browsing instruction above their decorative signs. -status: done ---- - -# US-011: Add readable physical-board signage - -As a **player**, I want readable signs on a generated quest board so that I know what it is and how to open it. - -## Acceptance criteria - -- [x] A generated physical board has a centered top sign reading `Quest Board` across its sign lines. -- [x] A centered sign immediately below instructs the player to right-click a sign below to browse quests. -- [x] The existing lower row retains three decorative signs with obfuscated or gibberish text. -- [x] All five signs and the visible oak planks open the globally shared quest-board interface. -- [x] New physical boards reserve and validate space for all five signs without overwriting blocks. -- [x] Existing generated boards with the prior three-sign layout are detected from their exact registered oak structure and upgraded with the two centered readable signs. -- [x] Existing custom single-block boards and unrelated structures are not modified. -- [x] Existing-board upgrades never overwrite occupied sign locations and persist new interaction locations failure-safely. -- [x] Automated tests verify sign placement, readable text, decorative text, interaction registration, obstruction handling, and prior-layout migration. -- [x] The title and instruction signs use glowing front-side text for readability while decorative signs remain non-glowing. -- [x] New boards receive glowing readable signs, and exact existing generated five-sign boards are refreshed on startup without modifying custom signs. - -## Related - -- [US-010: Generate a physical quest-board structure](us-010-generate-a-physical-quest-board.md) diff --git a/knowledge/user-stories/us-012-create-quests-near-a-board.md b/knowledge/user-stories/us-012-create-quests-near-a-board.md deleted file mode 100644 index 6ed0dac..0000000 --- a/knowledge/user-stories/us-012-create-quests-near-a-board.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -type: User Story -title: "US-012: Create quests by command near a board" -description: Allow command-based quest creation and material autocomplete near a physical board even when global player commands are disabled. -status: done ---- - -# US-012: Create quests by command near a board - -As a **player**, I want to use the quest-creation command near a quest board so that I can use material autocomplete while still interacting at the physical board. - -## Acceptance criteria - -- [x] When global player quest commands are disabled, `/quests create ` remains available to a player within five blocks of a registered board interaction location. -- [x] Material and quantity autocomplete remain available for nearby quest creation. -- [x] A player farther than five blocks from every registered board is directed to move closer and no quest or escrow change occurs. -- [x] Board proximity requires the player and registered location to be in the same world. -- [x] A distance of exactly five blocks is accepted and a greater distance is rejected. -- [x] Root listing, `list`, `complete`, `cancel`, and `claim` remain disabled while global player commands are disabled. -- [x] When global player quest commands are enabled, all command behavior, including creation, remains available regardless of board proximity. -- [x] Custom single-block boards and every registered interaction location on generated boards satisfy the proximity requirement. -- [x] Board-dialog creation remains available regardless of command settings or command proximity rules. -- [x] Automated tests verify boundaries, cross-world behavior, autocomplete, command settings, disabled subcommands, and generated-board proximity. - -## Related - -- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md) -- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-008: Control player quest commands](us-008-control-player-quest-commands.md) diff --git a/knowledge/user-stories/us-013-show-custom-reward-item-names.md b/knowledge/user-stories/us-013-show-custom-reward-item-names.md deleted file mode 100644 index 594d322..0000000 --- a/knowledge/user-stories/us-013-show-custom-reward-item-names.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -type: User Story -title: "US-013: Show custom reward item names" -description: Display a reward item's custom name together with its material type when browsing quests. -status: done ---- - -# US-013: Show custom reward item names - -As a **player**, I want named reward items identified by both custom name and material so that I understand exactly what a quest will award. - -## Acceptance criteria - -- [x] A reward with a custom display name is shown as amount, readable custom name, and material type, such as `1 × Shopping List (PAPER)`. -- [x] An unnamed reward continues to show its amount and material type, such as `3 × DIAMOND`. -- [x] Styled custom names are converted to safe readable plain text without changing the escrowed item's exact metadata. -- [x] Quest-board detail dialogs and `/quests` listings use the same reward representation. -- [x] Newly escrowed rewards persist the readable custom name alongside their exact serialized item data. -- [x] Existing persisted named rewards derive their custom name from valid stored item metadata when possible. -- [x] Missing, malformed, or unreadable item metadata safely falls back to the material type without preventing quest browsing. -- [x] Automated tests verify named, unnamed, styled, persisted, historical, and malformed reward metadata. - -## Related - -- [US-003: Create an item-delivery quest](us-003-create-a-block-delivery-quest.md) -- [US-004: Browse available quests](us-004-browse-available-quests.md)