feat(scengen): EnemyVisitor + ItemVisitor for distance-based content

[jmf-pobox]

Summary

• EnemyVisitor: places 5-tier enemies (rat→goblin→skeleton→troll→dragon) based on BFS distance from start. 40% spawn rate, skips hubs and start room, ±1 tier jitter.
• ItemVisitor: places 5-tier weapons/armor/potions scaled by distance. Starter weapon at distance 1, starter potion at start, potions at high-degree hubs.
• DefaultSpells(): adds fireball, heal, lightning, blessing to generated scenarios.
• Graph.MaxDistance(): BFS max depth for tier normalization.
• crypt-admin generate now wires all 3 visitors and prints stats.
• New make targets: generate-dungeon, validate-dungeon, eval-balance-generated, eval-balance-unix.

Balance results

38-room generated dungeon, 200 sessions:

• 61% survival (target: 50-75%)
• Mean level 2.0
• 10pp class spread (fighter 54%, mage 64%, priest 64%, thief 60%)

Test plan

• EnemyVisitor: distance scaling, hub skipping, spawn rate, difficulty progression
• ItemVisitor: starter weapon, potions at hubs, spell catalog, distance scaling
• End-to-end: make generate-dungeon → make validate-dungeon → make eval-balance-generated
• All existing tests pass (make check)

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces new procedural content generation logic (enemy/item placement and spell catalogs) and changes crypt-admin generate/export output, which can affect scenario balance and downstream validation but does not touch gameplay engine or auth/security code.

Overview
Adds distance-based content generation to internal/scengen by introducing EnemyVisitor (tiered enemy placement with spawn-rate/jitter, hub skipping) and ItemVisitor (tiered weapons/armor/potions plus optional default spell catalog), plus helper metrics like TotalXP/EnemyCount.

Extends Graph with MaxDistance() to normalize distance→tier mapping, and updates crypt-admin generate/export to run visitors in description → enemy → item order with a seeded RNG and to print basic generation stats.

Updates build tooling/docs: new Makefile targets for generating/validating a local dungeon tree and running balance evals on generated and unix-catacombs scenarios; CHANGELOG.md and .beads/issues.jsonl reflect the new visitors and related task status.

^{Written by Cursor Bugbot for commit 183b2e8. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

Adds distance-based population to the scenario generation pipeline so crypt-admin generate can produce larger, balance-testable dungeons with scaled enemies/items and a default spell catalog.

Changes:

• Introduces EnemyVisitor and ItemVisitor to place tiered enemies/items using BFS distance from the start (plus hub-aware rules).
• Adds Graph.MaxDistance() for max BFS depth (tier normalization).
• Wires new visitors into crypt-admin generate, adds Makefile targets for generating/validating/evaluating generated scenarios, and updates bead status.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
internal/scengen/enemy_visitor.go	New visitor that places enemies by distance tier with optional spawn rate and jitter.
internal/scengen/enemy_visitor_test.go	Tests for enemy placement, hub skipping, scaling, and spawn-rate edge cases.
internal/scengen/item_visitor.go	New visitor that places starter gear, tiered items, hub potions, and (optionally) default spells.
internal/scengen/item_visitor_test.go	Tests for starter weapon/potion placement, hubs, spell inclusion, and basic distribution.
internal/scengen/graph.go	Adds MaxDistance() BFS helper for tier normalization.
cmd/crypt-admin/main.go	Runs description → enemies → items visitors during generation and prints basic stats.
Makefile	Adds dungeon generation/validation and balance-eval convenience targets.
.beads/issues.jsonl	Updates issue statuses reflecting the scenario-gen work in progress/complete.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}