spigot-leaf/design/log.md

Leaf Design Log

2026-08-10

Initial protection design

• Leaf is available to any player who opts in; the seven-day period applies only to onboarding reminders.
• Protection grants Resistance I by default and remains active until the player opts out, attacks another player, an administrator disables it for the player, or Leaf is globally disabled.
• Receiving an attack does not remove protection, but retaliating does, including attributable Thorns damage.
• PvP attribution covers melee, projectiles, potions, owned animals, Thorns, and indirect damage when Spigot exposes a reliable responsible player.
• Opted-in players receive a leaf prefix in tab, overhead names, and chat where supported.
• New players receive an onboarding reminder on every login for seven calendar days after first joining.
• Global disablement suppresses effects, prefixes, and reminders without erasing player choices.
• Administration uses the permission-aware /leaf command tree with autocomplete.
• Builds and releases follow the neighboring Spigot Base Gradle and Gitea pipeline.
• The design bundle is committed together; later implementation work is committed separately for each user story.

Implementation started

• Established the Java 17 Gradle project, strict compilation, JUnit test lifecycle, Leaf plugin metadata, Gradle wrapper, and Gitea CI and semantic-release workflows.
• Verified the initial pipeline with ./gradlew clean check jar and produced build/libs/leaf-0.1.0-SNAPSHOT.jar.
• US-007 remains in progress until the story-by-story implementation commit requirement has been verified.

Configuration and persistence checkpoint

• Added validated settings with Resistance I and seven-day onboarding defaults.
• Added defensive UUID-keyed YAML player state with RFC 3339 timestamps, forward-field preservation, and atomic replacement where supported.
• Added safe plugin initialization and periodic dirty-state persistence.
• US-006 remains in progress pending live runtime setting commands and Leaf effect ownership behavior.

US-001 player protection completed

• Added permission-aware player commands with idempotent choice changes and detailed status reporting.
• Added immediate durable opt-in persistence, join-time restoration, and quiet infinite Resistance reconciliation.
• Leaf tracks its live Resistance fingerprint and conservatively preserves a visibly distinct Resistance effect.
• Verified player choice, lock, persistence, command, autocomplete, and build behavior with ./gradlew clean check jar.

US-003 identity presentation checkpoint

• Added configurable, color-compatible prefixes to standard chat display names and player-list names.
• Added conservative main-scoreboard team prefixes for overhead names without displacing unrelated teams.
• Name cleanup restores only values Leaf installed; third-party changes are preserved.
• Documented scoreboard, custom chat, tab-list, and per-viewer scoreboard limitations.
• US-003 remains in progress until combat and global administration paths are verified.

US-002 combat opt-out completed

• Added modern Spigot damage-source attribution for direct attacks, projectiles, thrown potions, area clouds, tamed animals, TNT, Thorns, and other reliably attributed sources.
• Ambiguous, cancelled, zero-damage, environmental, and self damage do not opt out a player.
• Combat opt-out bypasses administrative locks, immediately reconciles effect and prefix state, persists once, and sends one explanatory message.
• Verified attribution, victim safety, lock bypass, duplicate suppression, and the full build with ./gradlew clean check jar.

US-004 onboarding completed

• Join observation now sends the configurable welcome message on each login before the original first-join instant plus the configured calendar-day window.
• The exact expiration boundary and globally disabled behavior suppress reminders without resetting first-join state.
• The default message names all player commands and explains automatic combat opt-out.
• Verified repeated joins, expiration, global suppression, first-join retention, and the full build with ./gradlew clean check jar.

US-005 administration and US-003 identity completed

• Added the complete leaf.admin command tree for global state, live strength, player status, saved choice, and locks.
• Runtime global and strength changes persist before activation and immediately reconcile all online players.
• Target resolution prefers exact online/current names, retains prior names, accepts UUIDs, and rejects ambiguous reused names.
• Added position-specific administrative autocomplete and mutation/no-change reporting with validation before mutation.
• Verified global effect and prefix suppression/restoration, live strength, targets, locks, command permissions, completion, durable aliases, and the full build with ./gradlew clean check jar.

US-006 configuration and persistence completed

• Runtime global and Resistance-level changes are written through Bukkit configuration before becoming active and survive restart.
• Failed runtime setting persistence leaves the active settings unchanged.
• Leaf records only effects it successfully installs, removes them only while the visible fingerprint matches, and preserves distinct Resistance effects; Spigot's identical-effect ownership limitation is documented.
• Durable player state now retains prior names in addition to the required UUID, latest name, choice, lock, and RFC 3339 first-join timestamp.
• Verified settings failure safety, durable aliases, existing defensive YAML behavior, strict compilation, and the full build with ./gradlew clean check jar.

US-007 build and release completed

• Verified dedicated conventional implementation commits for protection, identity, combat, onboarding, administration, configuration verification, and logout cleanup in addition to the existing build foundation.
• Kept reserved OKF index and log documents in their specification-defined structures.
• Verified all user stories are done, all acceptance criteria are checked, the repository has no remote, and no push was performed.
• Final verification passed with ./gradlew clean check jar and okflint validation.

US-003 sticky-prefix regression fixed

• Reproduced the cleanup failure that occurred when another plugin changed a Leaf-decorated display name.
• Leaf now removes exact managed-prefix text without discarding surrounding third-party formatting, clears stale prefixes after reload, and normalizes repeated prefixes before applying one leaf.
• Added regression coverage for wrapped names, duplicate stale prefixes, untracked stale prefixes, unrelated formatting, tab names, and scoreboard cleanup.
• Verified the fix with ./gradlew clean check jar.

Strength protection added

• Opted-in players now receive quiet, infinite Strength I alongside Resistance I by default; both effects must be active for Leaf status to report active protection.
• Added independent resistance-level and strength-level settings with live /leaf effect <resistance|strength> <1-5> administration and positional autocomplete.
• Retained /leaf strength <1-5> as a deprecated compatibility alias for changing Resistance.
• Opt-out, combat, administrative disablement, and global disablement remove both Leaf-managed effects while conservatively preserving distinct external effects.
• Minecraft calculates the initiating PvP hit before Leaf can process the damage event, so that first hit can include the configured Strength bonus before automatic opt-out.
• Verified settings, runtime reconciliation, status, combat cleanup, persistence, command compatibility, autocomplete, and the complete build with ./gradlew clean check jar.

Automatic effect recovery added

• Leaf now reconciles opted-in online players every 20 ticks so death, milk, commands, and plugins cannot permanently clear configured protection.
• Recovery remains disabled for opted-out players and while Leaf is globally disabled.
• A temporary external Resistance or Strength effect is preserved instead of overwritten; the leaf prefix remains visible and Leaf restores its configured effect after the external effect ends.
• Added regression coverage for the one-second recovery task and eligibility-aware online-player reconciliation.
• Verified the complete build with ./gradlew clean check jar.