docs: define initial quest board stories

2026-09-04 23:21:53 -04:00
commit 97ad506ba7
12 changed files with 314 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Spigot Quest Board Agent Guide
+
+## Project
+
+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.
+
+## Canonical knowledge
+
+- `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.
@@ -0,0 +1,15 @@
+---
+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, block deliveries, item claims, player commands, administration, persistence, and plugin delivery requirements.
+
+## Explore
+
+- [User stories](user-stories/index.md)
+- [Knowledge log](log.md)
@@ -0,0 +1,22 @@
+---
+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-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.
@@ -0,0 +1,16 @@
+---
+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 a block-delivery quest](us-003-create-a-block-delivery-quest.md)
+4. [US-004: Browse available quests](us-004-browse-available-quests.md)
+5. [US-005: Deliver blocks 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)
+8. [US-008: Control player quest commands](us-008-control-player-quest-commands.md)
@@ -0,0 +1,28 @@
+---
+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: in-progress
+---
+
+# 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
+
+- [ ] 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.
+- [ ] Plugin metadata declares the entrypoint, player and admin commands, and permissions.
+- [ ] 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.
+- [ ] The project is published in the public `dmg/spigot-quest-board` Gitea repository.
+- [ ] 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)
@@ -0,0 +1,27 @@
+---
+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: backlog
+---
+
+# 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
+
+- [ ] An authorized administrator can use `/questadmin createboard` to register the block they are targeting.
+- [ ] Creation rejects a missing, invalid, or already registered target without changing state.
+- [ ] Registered boards persist across server restarts with their world and block coordinates.
+- [ ] Interacting with any registered board opens the quest-board interface.
+- [ ] Every registered board exposes the same global quests and claimable items.
+- [ ] The interface uses Purpur's supported native dialog API and follows the interaction style of Spigot Base.
+- [ ] Ordinary block interaction is not intercepted at unregistered locations.
+- [ ] Administrative actions require the `spigotquestboard.admin` permission, granted to server operators by default.
+- [ ] Automated tests verify board registration, persistence, shared visibility, authorization, and interaction routing.
+
+## Related
+
+- [US-003: Create a block-delivery quest](us-003-create-a-block-delivery-quest.md)
+- [US-004: Browse available quests](us-004-browse-available-quests.md)
@@ -0,0 +1,28 @@
+---
+type: User Story
+title: "US-003: Create a block-delivery quest"
+description: Let a player request block items while safely escrowing an inventory-funded reward.
+status: backlog
+---
+
+# US-003: Create a block-delivery quest
+
+As a **player**, I want to request a block material and quantity in exchange for items I already own so that another player can fulfill my request safely.
+
+## Acceptance criteria
+
+- [ ] A player can create a quest through a registered quest board by selecting a valid block material, a positive quantity, and reward items from their inventory.
+- [ ] Reward items must exist in the issuer's inventory and are removed only when quest creation succeeds.
+- [ ] Removed rewards are held durably in escrow by the quest system.
+- [ ] A created quest records a unique identifier, issuer UUID and current name, requested material and quantity, exact reward items, creation time, and expiration time.
+- [ ] Each quest expires exactly seven days after successful creation.
+- [ ] Invalid input, insufficient reward items, or persistence failure leaves the issuer's inventory unchanged and creates no quest.
+- [ ] When player commands are enabled, `/quests create ...` provides equivalent validated creation behavior with contextual autocomplete.
+- [ ] Quest state and item metadata survive server restarts without duplication or loss.
+- [ ] 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 blocks 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)
@@ -0,0 +1,25 @@
+---
+type: User Story
+title: "US-004: Browse available quests"
+description: Let players inspect globally available quests and their essential terms.
+status: backlog
+---
+
+# 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
+
+- [ ] Every registered board lists the same active quests.
+- [ ] Each listing shows the requested block material, quantity, reward, issuer, and time remaining.
+- [ ] Remaining durations are clear and never display an expired quest as active.
+- [ ] Completed, cancelled, and expired quests are excluded from the active listing.
+- [ ] When player commands are enabled, `/quests` and `/quests list` provide the same active quest information in chat.
+- [ ] Listing and autocomplete do not expose stale quest identifiers as completable or cancellable.
+- [ ] Automated tests verify filtering, displayed fields, duration boundaries, and command aliases.
+
+## Related
+
+- [US-002: Create and use shared quest boards](us-002-create-and-use-shared-quest-boards.md)
+- [US-005: Deliver blocks and complete a quest](us-005-deliver-blocks-and-complete-a-quest.md)
@@ -0,0 +1,29 @@
+---
+type: User Story
+title: "US-005: Deliver blocks and complete a quest"
+description: Let a player deliver requested blocks at a quest board and receive the escrowed reward.
+status: backlog
+---
+
+# US-005: Deliver blocks and complete a quest
+
+As a **player**, I want to deliver requested blocks to a quest board so that I receive the promised reward and the issuer can claim my delivery.
+
+## Acceptance criteria
+
+- [ ] An active quest offers a Complete Quest action through every registered board.
+- [ ] Completion requires the delivering player to possess the full requested quantity of the exact block material.
+- [ ] Successful completion removes the requested blocks from the delivering player's inventory and stores them as a claim for the issuer.
+- [ ] Successful completion gives the exact escrowed reward items to the delivering player.
+- [ ] Reward items that do not fit are dropped safely at the delivering player's feet with a clear message.
+- [ ] The issuer is notified immediately when online or on their next login when offline that delivered blocks can be claimed at a quest board.
+- [ ] When player commands are enabled, `/quests complete <quest>` provides equivalent behavior with contextual autocomplete.
+- [ ] Completion is atomic and exactly one player can complete a quest, including simultaneous attempts.
+- [ ] Validation or persistence failure does not consume delivered blocks, release rewards, or change quest state.
+- [ ] Completed quests are no longer shown as active or completable.
+- [ ] Automated tests verify inventory validation, settlement, overflow, notifications, rollback, and concurrent completion protection.
+
+## 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)
@@ -0,0 +1,27 @@
+---
+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: backlog
+---
+
+# 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
+
+- [ ] An issuer can cancel their own active quest through any registered board.
+- [ ] A player cannot cancel a quest issued by another player.
+- [ ] Completed, cancelled, and expired quests cannot be cancelled.
+- [ ] Cancellation removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer.
+- [ ] The reward is not inserted directly into the issuer's inventory during cancellation.
+- [ ] When player commands are enabled, `/quests cancel <quest>` provides equivalent behavior and only autocompletes the player's cancellable quest identifiers.
+- [ ] Cancellation and simultaneous completion are serialized so items cannot be duplicated or lost.
+- [ ] Persistence failure leaves the quest active and its reward escrowed.
+- [ ] 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)
@@ -0,0 +1,30 @@
+---
+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: backlog
+---
+
+# 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
+
+- [ ] An uncompleted quest expires seven days after its creation time.
+- [ ] Expiration removes the quest from active listings and converts its exact escrowed reward into a claim for the issuer.
+- [ ] Completed-quest claims contain the exact block items delivered by the completing player.
+- [ ] Claims from completion, cancellation, and expiration can be collected through any registered board.
+- [ ] The board clearly distinguishes delivered blocks from returned rewards.
+- [ ] Online issuers receive a real-time message when items become claimable.
+- [ ] Offline issuers receive a message on their next login.
+- [ ] When player commands are enabled, `/quests claim` collects the same pending claims.
+- [ ] Items are inserted into the claimant's inventory where space permits; overflow is dropped safely at their feet with a clear message.
+- [ ] A claim is removed only after all of its items have been inserted or dropped successfully.
+- [ ] Pending claims and notification state survive logout and server restart without duplication or loss.
+- [ ] Automated tests verify expiry boundaries, each claim source, notifications, overflow, failure recovery, and persistence.
+
+## Related
+
+- [US-005: Deliver blocks 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)
@@ -0,0 +1,27 @@
+---
+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: backlog
+---
+
+# 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
+
+- [ ] Player `/quests` commands are disabled by default.
+- [ ] An authorized administrator can use `/questadmin commands enable|disable` with contextual autocomplete.
+- [ ] The command setting persists across server restarts.
+- [ ] When disabled, `/quests`, `list`, `create`, `complete`, `cancel`, and `claim` reject execution with a clear message directing the player to a quest board.
+- [ ] Disabling commands does not prevent any equivalent action through a registered board.
+- [ ] `/questadmin` remains available to authorized administrators regardless of the player-command setting.
+- [ ] Unauthorized users cannot change the setting.
+- [ ] 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 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)