k8s.md compliance audit: 4-round codebase review

[abix-]

Summary

Full codebase audit against docs/k8s.md (Def/Instance/Controller architecture). Four sequential review rounds, each by a different agent, each building on the previous agent's findings.

Spec Doc

Spec: self-contained in issue body

Reference

• docs/k8s.md -- the authoritative architecture doc being audited against

Process

Each round is one agent dispatch cycle. The agent reads k8s.md, reviews the codebase, documents violations, and hands off to the next round.

Round 1: Inventory

• Read docs/k8s.md cover to cover
• Catalog every BuildingKind, BuildingDef, and BuildingInstance usage across the codebase
• List every match arm that switches on specific BuildingKind variants
• Document findings in a comment with file:line references

Round 2: Violation detection

• Read round 1 findings + k8s.md
• For each match arm from round 1, check: does this duplicate data that should come from the Def registry?
• Flag any instance field that caches a value already in the Def
• Flag any system that reads a hardcoded variant list instead of a Def field/flag
• Document violations with severity (blocker vs cleanup)

Round 3: Fix plan

• Read round 1+2 findings + k8s.md
• For each violation, propose the concrete fix (new Def field, registry lookup, etc.)
• Estimate scope: which files change, how many match arms collapse
• Group fixes into mergeable PRs (1 PR per logical change)
• Document the fix plan in a comment

Round 4: Verification

• Read all previous rounds + k8s.md
• Verify the fix plan is complete and correct
• Check for any violations missed in rounds 1-2
• Produce final summary: total violations, fix PRs needed, priority order
• Hand off to needs-human with the final report

Acceptance criteria

• Round 1: complete inventory of BuildingKind match arms with file:line refs
• Round 2: every match arm checked against k8s.md, violations flagged with severity
• Round 3: concrete fix plan with PR grouping for every violation
• Round 4: final verification pass confirms completeness, no missed violations
• All 4 rounds documented as issue comments with agent name and round number
• Final summary includes total violation count and priority-ordered fix list

[abix-]

Claude -- Round 1: Inventory

BuildingKind Enum

Defined at rust/src/world/mod.rs:487. 27 variants:

Fountain, Bed, Waypoint, Farm, FarmerHome, ArcherHome, Tent, GoldMine,
MinerHome, CrossbowHome, FighterHome, Road, StoneRoad, MetalRoad, Wall,
BowTower, CrossbowTower, CatapultTower, Merchant, Casino, TreeNode,
RockNode, LumberMill, Quarry, MasonHome, Gate, GuardTower

BuildingDef Struct

Defined at rust/src/constants/buildings.rs:86. Fields include: kind, display, tile, hp, cost, label, help, tooltip, player_buildable, raider_buildable, placement, is_tower, tower_stats, on_place, spawner, save_key, is_unit_home, worksite, autotile, tower_weapon_type, lod_color.

BUILDING_REGISTRY

rust/src/constants/buildings.rs:134 -- 28 entries, one per BuildingKind variant (Bed has no player-visible purpose but is registered). Lookup via building_def(kind) at line 841.

BuildingInstance Struct

rust/src/entity_map.rs:114 -- 5 fields only: kind, position, town_idx, slot, faction. Comment says "pure identity + spatial -- no gameplay state." Compliant with k8s.md slim-instance rule.

---

Match Arms Switching on Specific BuildingKind Variants

#	File:Line	Function/Context	Arms
1	rust/src/components.rs:737	ProductionState::take_yield	Farm, GoldMine, TreeNode, RockNode
2	rust/src/components.rs:751	ProductionState::yield_log_msg	Farm, GoldMine, TreeNode, RockNode
3	rust/src/npc_render.rs:861	Production overlay rendering	Farm, GoldMine, TreeNode, RockNode
4	rust/src/systems/work_targeting.rs:185	assign_worker_to_worksite	Farm, GoldMine, TreeNode/RockNode
5	rust/src/world/mod.rs:530	BuildingKind::road_build_radius	Road, StoneRoad, MetalRoad
6	rust/src/world/mod.rs:540	BuildingKind::road_pathfind_cost	Road, StoneRoad, MetalRoad

Hardcoded Variant Lists (matches! / equality / slice literals)

File:Line	Context	Variants
rust/src/messages.rs:182	mark_building_changed dirty routing	Farm, FarmerHome, ArcherHome, MinerHome
rust/src/messages.rs:178	mark_building_changed Waypoint patrol	Waypoint
rust/src/messages.rs:191	mark_building_changed mining dirty	MinerHome
rust/src/systemparams.rs:33	1-per-town Merchant limit	Merchant
rust/src/systemparams.rs:44	patrol_order init	Waypoint
rust/src/world/buildings.rs:302	GuardTower placement rule	GuardTower
rust/src/world/buildings.rs:310	GuardTower requires adjacent Wall	Wall
rust/src/world/buildings.rs:385	TreeNode/RockNode no-town rule	TreeNode, RockNode
rust/src/entity_map.rs:376	iter_mines helper	GoldMine
rust/src/entity_map.rs:399	find_farm_at helper	Farm
rust/src/entity_map.rs:407	find_mine_at helper	GoldMine
rust/src/systems/ai_player/squad_commander.rs:78	attack_kinds Aggressive	Farm, FarmerHome, ArcherHome, CrossbowHome, Waypoint, Tent, MinerHome
rust/src/systems/ai_player/squad_commander.rs:87	attack_kinds Balanced	ArcherHome, CrossbowHome, Waypoint
rust/src/systems/ai_player/squad_commander.rs:92	attack_kinds Economic	Farm
rust/src/systems/ai_player/squad_commander.rs:99	fallback_attack_kinds	Farm, FarmerHome, ArcherHome, CrossbowHome, Waypoint, Tent, MinerHome, Fountain
rust/src/constants/mod.rs:625	autotile_order full variant list	All 26 non-Bed variants

BuildingInstance Usage Summary

• Created in: world/buildings.rs:355, npc_render.rs:1252/1337/1344, systems/combat.rs:1333/1642/1657, systems/ai_player/build_actions.rs:616/653, save-load restore paths
• Iterated via EntityMap::iter_instances, iter_kind, iter_kind_for_town -- never raw loops over variant-specific arrays
• Queried via entity_map.find_farm_at, find_mine_at, iter_kind(GoldMine) helpers (hardcoded kind baked into method)

NPC Registry Cross-References

rust/src/constants/npcs.rs:411-741 -- NpcDef.home_building field references BuildingKind variants (FarmerHome, ArcherHome, Tent, FighterHome, MinerHome, CrossbowHome, LumberMill, Quarry, Fountain, MasonHome). This is a Def-to-Def reference inside the registry, which is correct pattern.

---

Round 1 complete. 6 match arms and 16 hardcoded variant list sites cataloged with file:line refs.

[abix-]

Claude

• Changed: Round 1 inventory complete -- no code changes, findings documented in comment above
• Tests: n/a (audit round, no code changes)
• Acceptance: 1/6 criteria met (Round 1 complete); Rounds 2-4 pending
• Open: No blockers; branch issue-247 pushed, no PR (no commits vs dev). Round 2 agent should read Round 1 findings, then check each match arm against k8s.md to flag violations with severity.
• Next: Round 2 -- violation detection: for each match arm from Round 1, determine whether it duplicates data that should come from the Def registry