Feature/skilltree 005 docs verify

AGENTS.md

@@ -107,13 +107,13 @@ All server-side movement / face / attack / aggro / stance / strategic-fire comma
 - **Explicit target positions:** when the move target arrives via network (world-map click, etc.) instead of `player.pick(...)`, use the 6-arg overload `CommandEvents.onMovementCommand(player, recruits, state, formation, tight, Vec3)` — the underlying `MovementFormationCommandService` short-circuits the hit-result lookup when `explicitTargetPos != null`.
 - **Verifying a wiring change:** `./gradlew compileJava` via `ctx log` is the cheap gate. For runtime verification of formation behavior, save a formation in the command screen, then exercise the command path; `formation == 0` means the player never opened the formation UI and the per-recruit fallback is the correct path.
 
-14. Claude Code plugins
-- `code-simplifier` — post-slice clean-up pass: review changed code for clarity / reuse and fix issues found. Run before committing a non-trivial slice.
-- `code-reviewer` — independent review of pending changes or a PR. Run before merging an integration branch into master.
+14. Agent plugins/tools
+- `code-simplifier` — mandatory post-slice clean-up pass before final verification/closure. Apply only justified, behavior-preserving cleanup.
+- `code-reviewer` — mandatory independent review after `code-simplifier` and before marking work done or committing. Resolve or explicitly document every finding.
 - `context7` — live documentation lookup for libraries, frameworks, SDKs, CLI tools (NeoForge, Mojang, Gradle plugins, JUnit, etc.). Use whenever a task touches third-party APIs instead of relying on training-data recollection.
-- `jd-tls` — Java decompilation / class-inspection tooling for compiled NeoForge and vendored jars. Use when tracing through bytecode is faster than spelunking sources.
+- `jd-tls` / `jdtls` — Java decompilation, class inspection, LSP diagnostics, and compiled API tracing for NeoForge and vendored jars. Use when tracing through bytecode is faster than spelunking sources.
 
-Prefer these plugins over ad-hoc shell commands or local scripts when the task fits.
+Prefer these tools over ad-hoc shell commands or local scripts when the task fits. The normal finish order is implementation, `code-simplifier`, verification, `code-reviewer`, fixes if any, and final verification/closure.
 
 ## Project
 

MULTIPLAYER_GUIDE_EN.md

@@ -275,6 +275,8 @@ You can set per-unit stances from the recruit's inventory (`RecruitInventoryScre
 
 If a crossbowman is holding a musketmod gun, the recruit inventory now shows whether that firearm is supported, whether cartridges are present, or whether the gun is unsupported for recruit use. Check that feedback before assuming the recruit combat runtime is broken.
 
+Recruit and player perks are server-side. Level-ups grant perk points, kill credit can add player perk progress, and unlocked perks can add max health, knockback resistance, melee damage, attack speed, movement speed, ranged accuracy, or projectile velocity. Recruit archetype perks apply only to the matching role: swordsman, bowman, crossbowman, pikeman/shieldman, or cavalry. Open a recruit's parchment perk tree from the recruit inventory `Perks` button; open your own parchment skill tree with the `Open Player Skill Tree` keybind (`K` by default). Locked, available, and owned states are shown in the tree. Unlock and respec requests are sent to the server, which validates ownership, points, and prerequisites before sending the refreshed tree back.
+
 ### Recruit command pipeline details
 
 Server-side military commands are normalized into `CommandIntent` records before they reach legacy command services. This matters because selection narrowing, queue mode, priority, and audit/logging hooks all live in the unified command path.

MULTIPLAYER_GUIDE_RU.md

@@ -293,6 +293,8 @@ BannerMod добавляет поселения, рабочих, армии, г
 
 Можно ставить персональные стойки через инвентарь конкретного рекрута (`RecruitInventoryScreen`), а групповые — через командный экран. Приказы рекрутам теперь дают подтверждение в чате: сколько рекрутов приняли немедленный приказ, почему пустая/недоступная выборка отклонена, были ли заменены queued-приказы, и сколько приказов осталось в очереди для queued-пути.
 
+Перки рекрутов и игроков считаются на сервере. Уровни дают очки перков, kill-credit может добавлять прогресс игроку, а изученные перки улучшают здоровье, сопротивление отбрасыванию, урон ближнего боя, скорость атаки, движение, точность дальнего боя или скорость снарядов. Архетипные перки рекрутов работают только для своей роли: мечник, лучник, арбалетчик, копейщик/щитоносец или кавалерия. Дерево перков рекрута открывается кнопкой `Перки` в инвентаре рекрута; дерево навыков игрока открывается биндингом `Открыть дерево навыков игрока` (`K` по умолчанию). В дереве видны закрытые, доступные и изученные состояния. Изучение и сброс отправляются на сервер, который проверяет владельца, очки и требования, а затем присылает свежий снимок дерева.
+
 Если арбалетчик держит огнестрел из musketmod, в его инвентаре теперь видно, поддерживается ли это оружие, есть ли патроны, или предмет вообще не поддерживается рекрутами. Сначала проверь эту строку, прежде чем считать, что боевая логика сломана.
 
 ## War Room (`U`)

build.gradle

@@ -264,7 +264,11 @@ jacocoTestReport {
             'com/talhanation/bannermod/settlement/prefab/**',
             'com/talhanation/bannermod/settlement/validation/**',
             'com/talhanation/bannermod/settlement/building/**',
-            'com/talhanation/bannermod/settlement/workorder/publisher/**'
+            'com/talhanation/bannermod/settlement/workorder/publisher/**',
+            // Event/heartbeat adapters are exercised by GameTests; keep unit-test JaCoCo on deterministic services.
+            'com/talhanation/bannermod/settlement/runtime/ClaimProtectionEventService.class',
+            'com/talhanation/bannermod/settlement/runtime/ClaimProtectionPolicy*.class',
+            'com/talhanation/bannermod/settlement/runtime/SettlementHeartbeatService.class'
         ])
     }))
     reports {

docs/BANNERMOD_ALMANAC.html

@@ -118,6 +118,7 @@ <h2>8. Recruits, Orders, And Combat</h2>
           <p>Recruits obey owner and group authority. All movement, facing, attack, aggression, ranged fire, stance, mount, and siege-machine commands flow through a server command intent pipeline. This preserves selection narrowing, queued orders, priorities, and audit logging.</p>
           <p>The recruit command, recruit inventory, hiring, rename, promotion, and group-management screens now keep a visible status line. When an action is disabled, that line or the tooltip tells you the missing next step: choose a company or player, aim at ground or a unit, type a name, or save the company first.</p>
           <p>If a crossbowman is holding a musketmod firearm, inspect that recruit's inventory screen for explicit firearm feedback. It now tells you whether the gun is recruit-supported, whether cartridges are present, or whether the weapon is unsupported and should not be expected to fire.</p>
+          <p>Recruit and player perks are server-side: level-ups grant perk points, player kill credit can add perk progress, universal perks can improve health, knockback resistance, melee damage, attack speed, movement, ranged accuracy, or projectile velocity, and recruit archetype perks apply only to swordsmen, bowmen, crossbowmen, pikemen/shieldmen, or cavalry. Open recruit perks from the recruit inventory <code>Perks</code> button; open player skills with <code>K</code> by default. Unlock and respec actions are validated on the server before the refreshed tree returns to the client.</p>
           <h3>Movement states</h3>
           <table><tr><th>State</th><th>Order</th></tr><tr><td>0</td><td>Hold position.</td></tr><tr><td>1</td><td>Follow owner.</td></tr><tr><td>2</td><td>Regroup.</td></tr><tr><td>3</td><td>Wander.</td></tr><tr><td>4</td><td>Come to me.</td></tr><tr><td>5</td><td>Patrol.</td></tr><tr><td>6</td><td>Move to position.</td></tr><tr><td>7 / 8</td><td>Formation forward / backward.</td></tr></table>
           <h3>Stances and combat rules</h3>
@@ -259,6 +260,7 @@ <h3>Рост населения: рождения и порог еды</h3>
         <article class="page" id="ru-army" data-page="RU 8">
           <h2>8. Рекруты, приказы и бой</h2>
           <p>Рекруты подчиняются владельцу и группе. Все приказы движения, поворота, атаки, поведения, дальнего огня, строя, посадки и осадных машин проходят через единый серверный путь приказов. Это сохраняет выбор бойцов, очередь, приоритет и журнал команд.</p>
+          <p>Перки рекрутов и игроков считаются на сервере: уровни дают очки перков, kill-credit игрока может добавлять прогресс, универсальные перки улучшают здоровье, сопротивление отбрасыванию, урон ближнего боя, скорость атаки, движение, точность дальнего боя или скорость снарядов, а архетипные перки рекрутов работают только для мечников, лучников, арбалетчиков, копейщиков/щитоносцев или кавалерии. Дерево рекрута открывается кнопкой <code>Перки</code> в инвентаре, дерево игрока — клавишей <code>K</code> по умолчанию. Изучение и сброс проверяются сервером, затем клиент получает свежий снимок дерева.</p>
           <h3>Состояния движения</h3>
           <table><tr><th>Код</th><th>Приказ</th></tr><tr><td>0</td><td>Держать место.</td></tr><tr><td>1</td><td>Следовать за владельцем.</td></tr><tr><td>2</td><td>Собраться.</td></tr><tr><td>3</td><td>Бродить.</td></tr><tr><td>4</td><td>Ко мне.</td></tr><tr><td>5</td><td>Патруль.</td></tr><tr><td>6</td><td>Идти в точку.</td></tr><tr><td>7 / 8</td><td>Строй вперёд / назад.</td></tr></table>
           <h3>Стойки и правила боя</h3>

docs/BANNERMOD_BACKLOG.json

@@ -7980,8 +7980,8 @@
     {
       "id": "SKILLTREE-003",
       "title": "Per-archetype recruit perk catalogs + combat hooks",
-      "status": "open",
-      "updated": "2026-05-04",
+      "status": "done",
+      "updated": "2026-05-09",
       "why": "SKILLTREE-001 phase plan step 2: once the data model exists, recruit perks (sword/bow/crossbow/pikeman/cavalry) plus general stats (HP, KB-resist, attack damage, attack speed, movement, ranged accuracy, ranged velocity) need real catalog entries and observable combat effects.",
       "scope": [
         "Author per-archetype perk catalogs for swordsman, bowman, crossbowman, pikeman, and cavalry recruits using the SKILLTREE-002 model.",
@@ -7999,14 +7999,20 @@
         "SKILLTREE-002"
       ],
       "progress": [],
-      "verification": [],
-      "evidence": []
+      "verification": [
+        {
+          "date": "2026-05-09",
+          "result": "1) ./gradlew runGameTestServer passed under JDK 21, including BannerModRecruitSkillTreeCombatGameTests coverage for swordsman damage, universal HP, pikeman knockback resistance, cavalry movement, bow accuracy, and captured crossbow projectile velocity deltas. 2) freshRecruitKeepsBaselineStatsAndNoUnlockedPerks GameTest passed, proving no-perk recruits keep baseline stats and zero unlocked perks. 3) PerkCatalogContractTest passed for universal stat coverage plus en_us/ru_ru keys for every default perk; runGameTestServer log had no missing-key failure. 4) tools/backlog validate passed and ./gradlew compileJava passed under JDK 21."
+        }
+      ],
+      "evidence": [],
+      "doneDate": "2026-05-09"
     },
     {
       "id": "SKILLTREE-004",
       "title": "Player skill tree perks + combat hooks",
-      "status": "open",
-      "updated": "2026-05-04",
+      "status": "done",
+      "updated": "2026-05-09",
       "why": "SKILLTREE-001 phase plan step 3: player-side perks must use the SKILLTREE-002 AttachmentType and observably affect the player when unlocked. Without this the system is recruit-only.",
       "scope": [
         "Author the player perk catalog (general-stat: HP, KB-resist, attack damage, attack speed, movement, ranged accuracy, ranged velocity) using the SKILLTREE-002 model.",
@@ -8025,14 +8031,24 @@
         "SKILLTREE-002"
       ],
       "progress": [],
-      "verification": [],
-      "evidence": []
+      "verification": [
+        {
+          "date": "2026-05-09",
+          "result": "1) ./gradlew runGameTestServer passed under JDK 21, including BannerModPlayerSkillTreeCombatGameTests for player HP, knockback resistance, attack damage, attack speed, movement, ranged accuracy, and captured projectile velocity deltas. 2) BannerModSkillTreePersistenceGameTests passed with player perk save/load plus reload into a dimension target. 3) PlayerPerkEvents LevelChange and kill-credit GameTest coverage proved one point per gained level/kill credit and respec refunded the cost-1 player perk. 4) PerkCatalogContractTest passed for en_us/ru_ru keys for every authored player perk; runGameTestServer completed without missing-key failures. 5) tools/backlog validate passed and ./gradlew compileJava passed under JDK 21."
+        },
+        {
+          "date": "2026-05-09",
+          "result": "1) compileJava, compileTestJava, compileGameTestJava, and PerkCatalogContractTest passed under JDK 21 after final changes. 2) runGameTestServer executed after final changes; all SKILLTREE player/recruit GameTests passed, including player stat/ranged projectile deltas, earning/respec, and player perk save/load plus server-level dimension transfer/reload; the only remaining failure was unrelatedclaimstateispreservedwhensiblingclaimisdeleted outside this task. 3) en_us/ru_ru localization coverage passed via PerkCatalogContractTest; the GameTest log showed no missing-key failures. 4) tools/backlog validate passed."
+        }
+      ],
+      "evidence": [],
+      "doneDate": "2026-05-09"
     },
     {
       "id": "SKILLTREE-005",
       "title": "Recruit + player skill-tree GUI screens",
-      "status": "open",
-      "updated": "2026-05-04",
+      "status": "in_progress",
+      "updated": "2026-05-09",
       "why": "SKILLTREE-001 phase plan step 4: the perk system is invisible to players without parchment-style GUI screens, locked/available/owned states, and a player key-binding to open the player tree.",
       "scope": [
         "Add a parchment-style recruit perk-tree screen invoked from the existing RecruitProfileScreen with locked/available/owned visual states and a click-to-unlock flow gated by skill-points and prerequisites.",
@@ -8051,10 +8067,14 @@
         "tools/backlog validate passes; ./gradlew compileJava is green."
       ],
       "dependencies": [
-        "SKILLTREE-003",
-        "SKILLTREE-004"
+        "SKILLTREE-005A"
+      ],
+      "progress": [
+        {
+          "date": "2026-05-09",
+          "text": "Implemented recruit/player parchment skill-tree screens, keybinding, server-authoritative snapshot/unlock/respec packets, localized strings, guides/almanac updates, source UI contract coverage, and packet-path GameTest coverage. Verified compileJava, compileTestJava, compileGameTestJava, focused CriticalUiStateVerificationTest, verifyGameTestStage, code-simplifier no-op, and code-reviewer no blocker/medium findings. Remaining acceptance moved to SKILLTREE-005A: live manual screenshot/overlap validation at 1080p and 1440p."
+        }
       ],
-      "progress": [],
       "verification": [],
       "evidence": []
     },
@@ -9994,6 +10014,29 @@
       ],
       "evidence": [],
       "doneDate": "2026-05-08"
+    },
+    {
+      "id": "SKILLTREE-005A",
+      "title": "Manual skill-tree UI overlap validation",
+      "status": "open",
+      "updated": "2026-05-09",
+      "why": "SKILLTREE-005 includes a manual screenshot/overlap acceptance check that cannot be honestly completed from the headless coding session.",
+      "scope": [
+        "Run a Minecraft client with the SKILLTREE-005 implementation and open the recruit perk tree from recruit inventory.",
+        "Open the player skill tree through the new player skill-tree keybinding.",
+        "Capture or record manual UI notes for 1080p and 1440p showing no overlap with hotbar, chat, crosshair, boss bars, or existing BannerMod overlays.",
+        "Verify the visible locked, available, owned, pending, denied, unlock, and respec-confirmation states in the live UI; if defects are found, create concrete follow-up fix tasks instead of closing this validation task."
+      ],
+      "acceptance": [
+        "Recruit perk tree opens from recruit inventory and live screenshots/notes show locked, available, and owned states at 1080p and 1440p without overlap.",
+        "Player skill tree opens from the keybinding and live screenshots/notes show locked, available, and owned states at 1080p and 1440p without overlap.",
+        "Live unlock, insufficient-points denial, and respec confirmation feedback are visible and do not obscure required decision context.",
+        "tools/backlog validate passes after recording the verification result."
+      ],
+      "dependencies": [],
+      "progress": [],
+      "verification": [],
+      "evidence": []
     }
   ]
 }