ik-codex/docs/superpowers/plans/2026-04-30-pz-analysers-pvp-admin.md

ProjectZomboid Phase B.2 Analysers — As-Built Plan

Retroactive: written 2026-05-01.

This document is a historical record of how Phase B.2 (PvP combat detection + admin verb dispatch) was implemented. The corresponding design spec is docs/superpowers/specs/2026-04-30-pz-analysers-pvp-admin-design.md. The work is complete and merged to master; checkboxes are pre-checked.

Goal: Land seven new Information insight classes (one for PvP combat, six for admin verbs) under src/Analysis/ProjectZomboid/, plus seven new pattern constants on PvpPattern / AdminPattern, then wire ProjectZomboidPvpLog and ProjectZomboidAdminLog default analysers to register them.

Architecture: Vanilla PatternAnalyser configured with the new insight classes. No custom Analyser subclasses (deferred to Phase B.3). Entry::__toString() joins lines with \n, but B.2 logs are single-line per entry so multi-line behaviour doesn't apply here.

Tech Stack: PHP 8.4+, PHPUnit 12, Composer (root package: indifferentketchup/codex). PHP/Composer not installed on host — all command invocations wrap in docker run --rm -v "$(pwd):/app" -w /app -u "$(id -u):$(id -g)" composer:latest ….

---

Tasks

Task 0 — Pre-checkpoint

• Empty checkpoint commit: df62da1 pre-phase-B.2 checkpoint

Task 1 — PvpDamageInformation + PvpPattern::COMBAT_REAL

• Add PvpPattern::COMBAT_REAL constant (combat regex with negative lookahead on weapon and positive-non-zero damage clause)
• Add src/Analysis/ProjectZomboid/PvpDamageInformation.php
• Add test/tests/Games/ProjectZomboid/Analysis/PvpDamageInformationTest.php covering pattern shape, match extraction, and three rejection cases (zombie weapon, zero damage, negative damage)
• composer test green: 167 tests, 343 assertions
• Commit: 55f769c Add PvpDamageInformation insight

Task 2 — AdminAddedItemInformation + AdminPattern::ADDED_ITEM_ENTRY

• Add AdminPattern::ADDED_ITEM_ENTRY constant (entry-anchored variant; the body-only ADDED_ITEM from Phase A stays in place)
• Add src/Analysis/ProjectZomboid/AdminAddedItemInformation.php
• Add test/tests/Games/ProjectZomboid/Analysis/AdminAddedItemInformationTest.php
• Commit: 90c85a0 Add AdminAddedItemInformation insight — see Deviations section below
• Forward-fix: 0d85a05 Fix missing closing brace in AdminPattern
• composer test green after forward-fix: 170 tests

Task 3 — AdminAddedXpInformation + ADDED_XP_ENTRY

• Add AdminPattern::ADDED_XP_ENTRY constant
• Add src/Analysis/ProjectZomboid/AdminAddedXpInformation.php
• Unit test
• composer test green: 173 tests
• Commit: a2faa55 Add AdminAddedXpInformation insight

Task 4 — AdminGrantedAccessInformation + GRANTED_ACCESS_ENTRY

• Add AdminPattern::GRANTED_ACCESS_ENTRY constant
• Add src/Analysis/ProjectZomboid/AdminGrantedAccessInformation.php
• Unit test
• composer test green: 175 tests
• Commit: caed04d Add AdminGrantedAccessInformation insight

Task 5 — AdminChangedOptionInformation + CHANGED_OPTION_ENTRY

• Add AdminPattern::CHANGED_OPTION_ENTRY constant
• Add src/Analysis/ProjectZomboid/AdminChangedOptionInformation.php
• Unit test
• composer test green: 177 tests
• Commit: b7b89ef Add AdminChangedOptionInformation insight

Task 6 — AdminReloadedOptionsInformation + RELOADED_OPTIONS_ENTRY

• Add AdminPattern::RELOADED_OPTIONS_ENTRY constant
• Add src/Analysis/ProjectZomboid/AdminReloadedOptionsInformation.php
• Unit test
• composer test green: 179 tests
• Commit: 64641fa Add AdminReloadedOptionsInformation insight

Task 7 — AdminTeleportedInformation + TELEPORTED_ENTRY

• Add AdminPattern::TELEPORTED_ENTRY constant (handles negative Z for basement coordinates)
• Add src/Analysis/ProjectZomboid/AdminTeleportedInformation.php
• Unit test (positive and negative Z cases)
• composer test green: 182 tests
• Commit: d15fc81 Add AdminTeleportedInformation insight

Task 8 — Wire ProjectZomboidPvpLog::getDefaultAnalyser()

• Replace return new PatternAnalyser(); with (new PatternAnalyser())->addPossibleInsightClass(PvpDamageInformation::class)
• Add test/tests/Games/ProjectZomboid/Analyser/PvpLogAnalysisTest.php — asserts three real-PvP insights (Bare Hands, Tire Iron, Hunting Knife) and zero zombie/vehicle insights
• composer test green: 184 tests
• Commit: 51eb2de Wire ProjectZomboidPvpLog default analyser

Task 9 — Wire ProjectZomboidAdminLog::getDefaultAnalyser()

• Register all six Admin<Verb>Information classes
• Add test/tests/Games/ProjectZomboid/Analyser/AdminLogAnalysisTest.php — asserts the 2+2+2+2+1+2 distribution and confirms the duplicate ShotgunShells row coalesces with counter == 2
• composer test green: 186 tests
• Commit: c57d646 Wire ProjectZomboidAdminLog default analyser

---

Deviations from the original plan

The 90c85a0 brace-fix interlude

Task 2's commit (90c85a0 Add AdminAddedItemInformation insight) shipped broken. While adding the first _ENTRY constant to AdminPattern.php, the Edit tool's old_string was <TELEPORTED line>\n} and the new_string included a docblock plus the new constant but dropped the closing brace of the class body. The commit was made before the test result was inspected, so it landed with a ParseError: Unclosed '{' and 9 cascading test errors.

Forward-fix 0d85a05 Fix missing closing brace in AdminPattern restored the brace as a separate commit (per the CLAUDE.md workflow rule: "Always create new commits rather than amending"). The broken intermediate commit remains in history; force-pushing master to clean it would have cost more than the cosmetic gain.

The remaining five admin commits (Tasks 3–7) used a deliberate practice change: every subsequent Edit to AdminPattern.php included the closing } in both old_string and new_string so it couldn't be dropped again. No further breakage.

Total commit count

11 commits vs the 10 originally outlined in the spec's planning section. The extra commit is the brace-fix.

Test-count divergence note (now resolved)

When Phase B.1's plan was written I projected a final count of 158 tests for B.1; the actual landed count was 161 (off by 3 — Task 5's contribution wasn't summed in the plan footer). For B.2 the planned and actual per-step counts match exactly. No projection error this phase.

---

Done condition (met)

After Task 9, composer test reports 186 tests, 387 assertions, all green under PHPUnit 12.5.6 / PHP 8.5.5 (verified via the composer:latest Docker image). All five originally-planned analysers from the Step D Phase B scope (B.1's three plus B.2's two) are now operational on their respective Log subclasses.