rpg-mcp

================================================================================ LIVING WORLD KERNEL UPGRADE - TRIAGE COMPLETE ================================================================================ Date: December 6, 2025 Status: ✅ READY FOR IMPLEMENTATION Confidence: 95% (High) ================================================================================ QUICK OVERVIEW ================================================================================ The "Living World" feature request is SOUND but needs to be split into TWO PHASES to maintain code quality: PHASE 1: Spatial Graph System (Rooms, persistence, exits) └─ Duration: 3-4 days └─ Status: ✅ READY (See HANDOFF_LIVING_WORLD_PHASE_1.md) └─ Blocker: None (independent) PHASE 2: Social Hearing Mechanics (Overhearing, stealth rolls) └─ Duration: 4-5 days └─ Status: 🟡 DEFERRED (Need Phase 1 + game design input) └─ Blockers: EDGE-001, EDGE-006 (2 small edge case fixes) PHASE 3: Auto-Mender/Dev Tools └─ Duration: 1-2 days └─ Status: ⏸️ DEFERRED TO WAVE 5 (not urgent) ================================================================================ THE GAPS WE FOUND ================================================================================ Gap 1: Scope Confusion ├─ Request mixes 3 distinct features (rooms, hearing, dev tools) ├─ Should be 3 separate PRs with different acceptance criteria └─ FIX: Break into phases (Done in HANDOFF_LIVING_WORLD_PHASE_1.md) Gap 2: Missing Game Design Rules ├─ "Implement hearing ranges" without defining ranges (5 feet? 30? 100?) ├─ No formula for how perception stats map to listening distance ├─ No rules for different volumes (whisper vs shout) └─ FIX: Phase 2 defines these explicitly (see TRIAGE document) Gap 3: Incomplete Architecture ├─ Request assumes observer.stats.perception (doesn't exist) ├─ No specification of how RoomNode relates to worldgen tiles ├─ Missing character.currentRoomId column └─ FIX: HANDOFF document specifies all missing schema changes Gap 4: Unresolved Blocking Issues ├─ EDGE-001: Characters can "steal from themselves" ├─ EDGE-006: Theft victims can become fences for their own stolen goods ├─ NEW-MECH-001: Mechanical transfers not implemented (narrative-only mode) └─ FIX: Listed as preconditions in Phase 2 ================================================================================ 70% INFRASTRUCTURE ALREADY EXISTS ================================================================================ You don't need to build from scratch: ✅ SpatialEngine (pathfinding, collision, AoE) └─ Located: src/engine/spatial/engine.ts └─ Use this for room positioning ✅ NPC Memory System (conversation recording) └─ Located: src/server/npc-memory-tools.ts └─ 6 tools already exposed in MCP registry ✅ Character Repository (CRUD operations) └─ Located: src/storage/repos/character.repo.ts └─ Model your SpatialRepository after this ✅ Repository Pattern (established throughout) └─ All data access flows through repos └─ Never raw SQL in tools ✅ Zod Schema Validation (comprehensive) └─ Located: src/schema/*.ts └─ Use this pattern for RoomNode schema ✅ 659 Existing Tests └─ Use as models for your new tests └─ Follow Vitest patterns established ================================================================================ DOCUMENTS CREATED ================================================================================ 1. TRIAGE_LIVING_WORLD_KERNEL.md (FULL ANALYSIS) ├─ 10 detailed sections ├─ Architecture compliance check ├─ Risk assessment ├─ Game design decisions needed ├─ Dependency mapping └─ Success criteria 2. HANDOFF_LIVING_WORLD_PHASE_1.md (IMPLEMENTATION SPEC) ├─ Exact code structures to implement ├─ All 5 deliverables specified in detail ├─ 15+ test cases fully written out ├─ Database schema with constraints ├─ MCP tool signatures ├─ Implementation checklist ├─ Success criteria (acceptance tests) └─ Ready to hand to Claude Code 3. TRIAGE_SUMMARY.txt (THIS FILE) └─ Quick reference, executive summary ================================================================================ KEY FINDINGS ================================================================================ WHAT'S WRONG WITH THE ORIGINAL REQUEST: ❌ Conflates rooms, hearing, and dev tools into one PR ❌ Missing game design (hearing range formulas) ❌ References non-existent fields (observer.stats.perception) ❌ Doesn't account for 70% existing infrastructure ❌ Would create untestable, unmaintainable code if implemented as-is THE FIX: ✅ Split into phases ✅ Explicit game design decisions ✅ Detailed schema specifications ✅ Reuse existing patterns (repos, zod, testing) ✅ Clear acceptance criteria for each phase BLOCKING ISSUES TO FIX BEFORE PHASE 2: 1. EDGE-001: Self-theft prevention (30 min fix) 2. EDGE-006: Victim/fence conflict (15 min fix) 3. Add perception/stealth to character stats (45 min fix) Total: ~1.5 hours ================================================================================ RECOMMENDED SEQUENCE ================================================================================ IMMEDIATE (Phase 1): 1. Read HANDOFF_LIVING_WORLD_PHASE_1.md 2. Start with schema (src/schema/spatial.ts) 3. Implement repository (src/storage/repos/spatial.repo.ts) 4. Add database migration (src/storage/migrations.ts) 5. Write tests FIRST (tests/spatial-graph.test.ts) 6. Implement tools (src/server/spatial-tools.ts) 7. Register tools (src/server/index.ts) 8. Commit when all tests pass FOLLOW-UP (Before Phase 2): 1. Fix EDGE-001 (self-theft logic flaw) 2. Fix EDGE-006 (victim/fence conflict) 3. Add perception/stealth stats to character schema 4. Review game design decisions in TRIAGE document FUTURE (Phase 2): 1. Implement hearing radius calculations 2. Implement witness loop with stealth checks 3. Extend npc-memory-tools.ts with interact_socially 4. Write 20+ tests for hearing mechanics LATER (Phase 3): 1. Implement report_anomaly tool 2. Add bug capture/serialization ================================================================================ ESTIMATED TIMELINE ================================================================================ Phase 1 (Spatial Graph): 3-4 days ├─ Schema & repo: 1 day ├─ Database & migration: 0.5 day ├─ Tools: 0.5 day ├─ Tests: 1 day └─ Polish & debugging: 0.5-1 day Blocking fixes: 1-2 hours ├─ EDGE-001 fix: 30 min ├─ EDGE-006 fix: 15 min └─ Add stats: 45 min Phase 2 (Hearing): 4-5 days ├─ Design review: 4 hours (before coding!) ├─ Engine logic: 1 day ├─ Tools: 1 day ├─ Tests: 1 day └─ Integration: 0.5-1 day TOTAL: ~2 weeks of focused development ================================================================================ SUCCESS METRICS ================================================================================ Phase 1 is DONE when: ✅ All 15+ tests pass ✅ `npm run build` succeeds ✅ Rooms can be created and persisted ✅ Room descriptions are immutable (locked after creation) ✅ Perception-based exit filtering works ✅ Rooms link via exits to other rooms Phase 2 is DONE when: ✅ Whispers only heard by target + immediate neighbors ✅ Shout heard across entire location ✅ Stealth vs Perception rolls working correctly ✅ Eavesdroppers see "overheard" entries in memory ✅ 20+ integration tests pass ================================================================================ DECISION CHECKLIST FOR YOU ================================================================================ Before starting implementation, confirm: [ ] Do you want Phase 1 only (rooms), or rooms + hearing? Recommend: Phase 1 now, Phase 2 in next sprint [ ] Hearing range formula preference (A, B, or C)? Recommend: Option C (environment-aware) for immersion [ ] Should perception use WIS modifier, or separate stat? Recommend: Use WIS modifier (D&D standard) [ ] Are rooms different from worldgen tiles, or same thing? Recommend: Different (semantic location vs physical grid) [ ] Should LLM be able to change room descriptions? Recommend: No (descriptions locked after creation) ================================================================================ NEXT STEPS ================================================================================ IF IMPLEMENTING PHASE 1: 1. Read HANDOFF_LIVING_WORLD_PHASE_1.md (complete spec) 2. Start implementing with TDD (test first) 3. Follow the checklist in the handoff document 4. Run tests frequently: npm test -- tests/spatial-graph.test.ts 5. Commit when tests pass IF NEED CLARIFICATION: 1. See TRIAGE_LIVING_WORLD_KERNEL.md for detailed analysis 2. Game design decisions are in Part 6 3. Risk assessment in Part 3 4. Dependency mapping in Part 7 IF READY TO START PHASE 2: 1. Fix blocking issues first (EDGE-001, EDGE-006) 2. Read Phase 2 spec (in TRIAGE document, Part 2) 3. Confirm game design decisions 4. Follow Phase 2 implementation guide ================================================================================ DOCUMENT REFERENCE ================================================================================ TRIAGE_LIVING_WORLD_KERNEL.md: Part 1: Architectural Analysis (what exists, what's missing) Part 2: Integration Analysis (how it fits in) Part 3: Risk Assessment (what could go wrong) Part 4: Required Game Design Decisions (what you need to decide) Part 5: Success Criteria (rewritten phases 1-3) Part 6: Game Design Decisions (detailed options) Part 7: Dependency Mapping (what blocks what) Part 8: Architecture Compliance (does it follow patterns?) Part 9: Known Issues to Fix First Part 10: Recommended Handoff Structure HANDOFF_LIVING_WORLD_PHASE_1.md: Complete implementation specification for Phase 1 (rooms) Includes: schema, repository, migration, tools, tests Ready to hand to Claude Code TRIAGE_SUMMARY.txt: This file - quick reference guide ================================================================================ BOTTOM LINE ================================================================================ The "Living World" feature is fundamentally sound, but the original request needs to be split into phases and clarified with explicit game design decisions. We've done the hard work: ✅ Analyzed what exists (70% already built) ✅ Identified the gaps ✅ Structured it into phases ✅ Written detailed specs ✅ Provided complete code examples Result: A rock-solid implementation plan that respects the existing architecture and can be executed in 2 weeks of focused work. Ready to implement? Start with HANDOFF_LIVING_WORLD_PHASE_1.md Questions? See TRIAGE_LIVING_WORLD_KERNEL.md for detailed analysis. ================================================================================