docs(design): define Tree Feller user stories

2026-08-11 17:07:13 -04:00
commit de27d6519e
12 changed files with 333 additions and 0 deletions
@@ -0,0 +1,37 @@
+---
+type: User Story
+title: "US-008: Configure and persist Tree Feller"
+description: Provide validated configuration and durable player state for predictable tree-felling behavior.
+status: backlog
+---
+
+# US-008: Configure and persist Tree Feller
+
+As a **server operator**, I want Tree Feller's behavior and player progression stored safely so that upgrades and restarts do not cause surprises or lost progress.
+
+## Acceptance criteria
+
+- [ ] Configuration defines supported species and their thresholds, each defaulting to 100 qualifying blocks.
+- [ ] Configuration defines an animation delay defaulting to two server ticks per felled block.
+- [ ] Configuration defines a progress boss-bar timeout defaulting to five seconds and an undo window defaulting to six minutes.
+- [ ] Configuration includes bounded tree-search limits, boss-bar presentation, title timing, and all player-facing messages.
+- [ ] Numeric settings reject zero, negative, overflowing, or operationally unsafe values using documented bounds.
+- [ ] Invalid required configuration prevents partial plugin initialization and produces a clear server log message identifying the setting.
+- [ ] Runtime threshold changes made through `/treefelleradmin` are persisted before becoming active and survive restart.
+- [ ] A failed runtime configuration write leaves the active threshold unchanged.
+- [ ] UUID-keyed player state persists latest known name, enabled preference, administrative lock, per-species progress, and earned unlocks.
+- [ ] Player identity resolution safely retains previously known names while UUID remains authoritative.
+- [ ] Player state is written atomically where supported so that a failed write does not replace valid state with a partial document.
+- [ ] Corrupt or invalid player records are handled defensively and cannot silently grant unlocks or administrative privileges.
+- [ ] Progress that exceeds a currently configured threshold is retained, and counters cannot overflow.
+- [ ] Unknown forward-compatible configuration and player-state fields are preserved where practical.
+- [ ] Undo records are runtime safety records and do not survive a server restart unless a later approved design explicitly adds durable undo.
+
+## Related
+
+- [US-001: Earn tree-type unlocks](us-001-earn-tree-type-unlocks.md)
+- [US-002: View tree progress](us-002-view-tree-progress.md)
+- [US-003: Fell unlocked trees](us-003-fell-unlocked-trees.md)
+- [US-005: Undo the last felled tree](us-005-undo-the-last-felled-tree.md)
+- [US-007: Administer Tree Feller](us-007-administer-tree-feller.md)
+- [US-009: Build and release Tree Feller](us-009-build-and-release-tree-feller.md)