Updates docs.

docs/Modernize.md

@@ -0,0 +1,128 @@
+# Score Keeper Modernization Plan
+
+Current baseline: October 2026. This replaces
+[the historical Cursor plan](../.cursor/plans/Modernize.md) as the maintained
+roadmap. It is a plan, not authorization to change runtime behavior or publish.
+Read [CONTRIBUTING.md](../CONTRIBUTING.md) and [AGENTS.md](../AGENTS.md) first.
+
+## Baseline: already implemented
+
+The old Maven/Java 17/older Minecraft migration is no longer pending.
+
+| Area | Current implementation |
+| --- | --- |
+| Build | Gradle 9.8.0 wrapper, Java 25 toolchain, Foojay resolver, configuration cache, Spotless |
+| Paper target | API `26.2.build.129-stable`, manifest API `26.2`, documented Paper 26.2/26.3 support |
+| Identity and messaging | UUID-based scores, Paper/Adventure messages, plugin logger, online `getPlayerExact` lookup |
+| Domain | Named buckets, initial values, four reporting policies, default/individual assignments |
+| Persistence | Version-3 scores YAML, archives YAML, legacy flat UUID score loading, shutdown save/enable load |
+| Competitions | Target/timed/manual runs, scheduled checks, top-N rankings, score snapshots/restoration |
+| Tooling | Bash build/deploy/server/backup/restore/local and Modrinth publishing; legacy PowerShell subset |
+| Documentation | Contributor entry point, shared agent rules, current domain/integration references, manual release checklist, schema-shaped project metadata |
+
+Implemented is not the same as verified on every advertised server version.
+There are no automated Java tests yet; the CI `test` task is currently `NO-SOURCE`.
+There is no real-server integration task and no automatic publishing workflow.
+
+## Phase 1: reliable regression coverage (SK-08 through SK-11)
+
+These are prerequisites for changing persistence, permissions, arithmetic, or
+run behavior. Keep the default test task server-free.
+
+- [ ] Add JUnit 5 infrastructure and an in-memory Paper harness compatible with
+  the current Java/Paper API (for example, MockBukkit if compatible). Use Mockito
+  only for narrow boundaries where a harness is unnecessary; verify compatibility
+  before choosing/pinning dependencies.
+- [ ] Cover bucket ID/label/reporting validation, duplicates, initial values,
+  UUID isolation, lazy reads, active/default selection, all-player assignment
+  clearing, and signed add/subtract/reset semantics.
+- [ ] Cover YAML round trips in temporary data directories: buckets, scores,
+  assignments, runs/snapshots, archives, and legacy flat scores. Include invalid
+  UUIDs, unknown buckets, malformed values, and empty archive buckets.
+- [ ] Cover all eight command executors: sender/self/online-target resolution,
+  literal reset booleans, duration units/overflow, usage/errors, and existing
+  permission boundaries.
+- [ ] Verify Adventure reporting audiences, changed-vs-unchanged scores, unit
+  labels, self/other bucket notices, and no duplicate run change notifications.
+- [ ] Introduce a small controllable clock/scheduler seam where necessary for
+  deterministic run tests; avoid a wholesale architecture rewrite.
+- [ ] Verify descending/name/UUID run ties, archive UUID ties, offline/unranked
+  entries, top-N boundaries, immediate targets, duration expiration, manual stop,
+  resumed runs, and exact pre-run score restoration (including new run entrants).
+- [ ] Make CI produce real test reports and fail on these regressions once tests
+  exist; do not mistake missing reports for tested coverage.
+
+## Phase 2: explicit real-server validation (SK-12)
+
+- [ ] Add an opt-in `integrationTest` source set/task only for behavior requiring
+  actual Paper. Keep it out of normal `test`/`build`, use disposable directories,
+  and own/stop only the processes it starts.
+- [ ] Load the built jar on both Paper 26.2 and 26.3 with Java 25; verify real
+  command registration/dispatch, Adventure output, scheduler completion, API
+  integration/load order, and persistence across clean restarts.
+- [ ] Run [human-tests.md](human-tests.md) on both versions before release.
+  Record artifact version, Paper build, Java version, observations, and logs.
+- [ ] Review startup/runtime deprecation warnings and unsupported API calls
+  found by builds/runtime tests; update compatibility claims only with evidence.
+
+Do not broaden support to Spigot, Bukkit, Folia, or future Paper versions by
+documentation changes alone.
+
+## Phase 3: persistence and correctness hardening
+
+Choose behavior changes explicitly and add regression tests first.
+
+- [ ] Design safe periodic/dirty-state saves or explicit saves so crashes do not
+  lose all changes since shutdown. Decide save cadence and I/O threading while
+  snapshotting mutable state on the main thread.
+- [ ] Design atomic replacement/recovery and consistency between score resets
+  and archives across the two YAML files. Preserve or migrate legacy data, and
+  ensure save failures are visible to administrators/callers.
+- [ ] Define validation rules for malformed YAML rather than relying on defaulting
+  getters. Cover invalid integer types, assignments, missing archive fields,
+  empty snapshots, and recovery without overwriting good data.
+- [ ] Decide whether integer overflow should fail, clamp, or use a wider score
+  type. Preserve negative-score use cases and provide an explicit data/API
+  migration if the type changes.
+- [ ] Review the misleading `until-disabled` mode name: document current
+  resume-across-disable behavior until any new end-on-disable mode is deliberately
+  designed. Do not silently rename the command or change saved lifetime values.
+
+## Phase 4: command and integration ergonomics
+
+- [ ] Design permission nodes/defaults for score get/add/subtract/reset and archive
+  listing; define self-vs-other access and a migration strategy before restricting
+  currently open commands.
+- [ ] Implement SK-13: explicit bucket selection for `/score-get`, with unambiguous
+  syntax, validation, help, docs, and tests. Preserve existing optional-player usage.
+- [ ] Align manifest/executor help with supported archive scopes, reporting
+  arguments, and literal reset booleans; consider tab completion as a separate
+  tested improvement.
+- [ ] Evaluate a smaller API/domain boundary only where needed for tested
+  behavior or companion integration. Retain public overload compatibility and
+  avoid unnecessary service abstractions.
+
+## Phase 5: safer developer and release tooling
+
+- [ ] Scope Bash start/stop/backup/restore process checks to the configured server
+  or a verified owned PID; never stop another project's Paper process.
+- [ ] Verify the bootstrap helpers select an actual Java 25 JDK, not merely the
+  first cached Java executable, and document supported hosts.
+- [ ] Bring PowerShell setup/configuration/process management to deliberate
+  parity with Bash or clearly retain a reduced supported surface. Prefer graceful
+  shutdown over forced termination.
+- [ ] Make deployment select/verify the intended artifact and version instead of
+  relying only on newest modification time and a stale-source warning.
+- [ ] Add lightweight local-link and JSON Schema checks for docs/metadata to CI,
+  keeping the scraper's slug-keyed contract and existing filenames.
+- [ ] Rehearse a tagged release: rebuild after tagging, verify manifest/version,
+  run manual checks, review changelog and compatibility, upload deliberately, and
+  update hosted Modrinth description separately.
+
+## Completion criteria
+
+A modernization item is done only when its behavior and failure modes have
+appropriate tests or recorded manual evidence, directly related docs are current,
+and existing data/API contracts are preserved or explicitly migrated. Use
+[TODO.md](../TODO.md) for SK feature/task status; this plan organizes the broader
+work and must not mark unchecked tests or future infrastructure as implemented.