Implement devotee auto-deposit to player storage #250

New issue

Open

opened 2026-03-16 01:41:48 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:41:48 +00:00

Owner

Metadata

Field	Value
Parent Epic	Epic: Storage & Trade (#212)
Legendary	Crafting & Resource Economy (#200)
Type	Feature
Priority	Medium
MoSCoW	Should Have
Points	3
Branch	`feature/m4-devotee-auto-deposit`
Commit Message	`Implement devotee auto-deposit to player storage (#250)`

Background and Context

This feature connects the devotee-delegated harvesting system with the personal storage chest. When a devotee is assigned to harvest resources, those resources should be automatically deposited into the player's personal storage chest rather than remaining in the devotee's non-existent inventory or disappearing into the void.

This is the logistical backbone of passive resource gathering — without auto-deposit, devotee harvesting would be incomplete. The feature must handle edge cases like a full storage chest, a missing/destroyed storage chest, and multiple devotees depositing simultaneously.

Expected Behavior

When a devotee harvests a resource (via the devotee-delegated harvesting system), the resource is automatically added to the player's personal storage chest.
If the storage chest is full, the devotee pauses harvesting and the player receives a notification that their storage is full.
If the player does not have a storage chest, the devotee holds up to 5 items and then pauses, notifying the player.
When the storage chest has space again (player retrieves items), the devotee resumes harvesting automatically.
A log of recent auto-deposits is available via the devotee status command.

Acceptance Criteria

Devotees automatically deposit harvested resources into the player's personal storage chest.
If the storage chest is full, the devotee pauses harvesting.
The player receives a notification when the devotee pauses due to full storage.
If no storage chest exists, the devotee buffers up to 5 items then pauses.
Devotees automatically resume harvesting when storage space becomes available.
The devotee status command shows recent auto-deposit activity.
Auto-deposit works correctly with multiple devotees depositing concurrently.

Subtasks

Implement the auto-deposit hook in the devotee harvesting cycle to target the player's storage chest.
Implement full-storage detection and devotee pause behavior.
Implement player notification when devotee pauses due to full storage.
Implement fallback buffer (5 items) when no storage chest exists.
Implement automatic resume when storage space becomes available.
Add recent auto-deposit log to the devotee status command output.
Handle concurrent deposits from multiple devotees safely.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/devotee_auto_deposit.feature covering deposit to chest, full chest pause, no chest fallback, resume on space, concurrent deposits, status log.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for devotee harvest-to-storage end-to-end flow.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |---|---| | **Parent Epic** | Epic: Storage & Trade (#212) | | **Legendary** | Crafting & Resource Economy (#200) | | **Type** | Feature | | **Priority** | Medium | | **MoSCoW** | Should Have | | **Points** | 3 | | **Branch** | `feature/m4-devotee-auto-deposit` | | **Commit Message** | `Implement devotee auto-deposit to player storage (#250)` | ## Background and Context This feature connects the devotee-delegated harvesting system with the personal storage chest. When a devotee is assigned to harvest resources, those resources should be automatically deposited into the player's personal storage chest rather than remaining in the devotee's non-existent inventory or disappearing into the void. This is the logistical backbone of passive resource gathering — without auto-deposit, devotee harvesting would be incomplete. The feature must handle edge cases like a full storage chest, a missing/destroyed storage chest, and multiple devotees depositing simultaneously. ## Expected Behavior 1. When a devotee harvests a resource (via the devotee-delegated harvesting system), the resource is automatically added to the player's personal storage chest. 2. If the storage chest is full, the devotee pauses harvesting and the player receives a notification that their storage is full. 3. If the player does not have a storage chest, the devotee holds up to 5 items and then pauses, notifying the player. 4. When the storage chest has space again (player retrieves items), the devotee resumes harvesting automatically. 5. A log of recent auto-deposits is available via the devotee status command. ## Acceptance Criteria - [ ] Devotees automatically deposit harvested resources into the player's personal storage chest. - [ ] If the storage chest is full, the devotee pauses harvesting. - [ ] The player receives a notification when the devotee pauses due to full storage. - [ ] If no storage chest exists, the devotee buffers up to 5 items then pauses. - [ ] Devotees automatically resume harvesting when storage space becomes available. - [ ] The devotee status command shows recent auto-deposit activity. - [ ] Auto-deposit works correctly with multiple devotees depositing concurrently. ## Subtasks - [ ] Implement the auto-deposit hook in the devotee harvesting cycle to target the player's storage chest. - [ ] Implement full-storage detection and devotee pause behavior. - [ ] Implement player notification when devotee pauses due to full storage. - [ ] Implement fallback buffer (5 items) when no storage chest exists. - [ ] Implement automatic resume when storage space becomes available. - [ ] Add recent auto-deposit log to the devotee status command output. - [ ] Handle concurrent deposits from multiple devotees safely. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/devotee_auto_deposit.feature` covering deposit to chest, full chest pause, no chest fallback, resume on space, concurrent deposits, status log. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for devotee harvest-to-storage end-to-end flow. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.