Phase 5: Analysis Enhancement & Migration

[discreteds]

Overview

Update kleene-analyze to handle dynamic edges (improvisation), add comprehensive validation, create templates, and write migration documentation.

Deliverables

Reachability Algorithm Rewrite

• Distinguish static edges (next_node) from dynamic edges (next: improvise)
• Report improvisation outcome nodes as "conditionally reachable"
• Show pattern matching info (permits/blocks) for dynamic edges
• Fix false "unreachable node" warnings for improvisation outcomes

Schema Validation

• Location state consistency checks
• Node precondition reachability analysis
• Location precondition circular dependency detection
• Temporal event consistency validation
• NPC location reference validation

Template Scenarios

• Create TEMPLATES/advanced.yaml demonstrating all features
• Create TEMPLATES/temporal_example.yaml for time system showcase
• Include examples of: location state, node preconditions, location gating, NPCs, events

Documentation

• Write lib/guides/migration-v2.md with before/after examples
• Write lib/guides/best-practices.md covering:
  • Location state management patterns
  • Temporal design patterns
  • NPC movement patterns
  • Event scheduling strategies
• Update lib/framework/core.md to clarify improvisation routing

Analysis Output Example

REACHABILITY ANALYSIS
─────────────────────
Static nodes: 25 reachable
Dynamic nodes: 10 conditionally reachable (improvisation outcomes)

IMPROVISATION COVERAGE
──────────────────────
pub_unknown → permits: ["drink", "chat"], blocks: ["fight"]
  → pub_drinks (matched: "drink")
  → pub_chat (matched: "chat")
  → pub_hostile (blocked: "fight")

SCHEMA VALIDATION
─────────────────
✓ All location references valid
✓ No circular precondition dependencies
✓ Temporal events reference valid nodes
⚠ NPC 'merchant' not defined in npc_locations

Files to Create/Modify

• kleene/skills/kleene-analyze/SKILL.md (reachability algorithm, validation)
• kleene/scenarios/TEMPLATES/advanced.yaml (NEW)
• kleene/scenarios/TEMPLATES/temporal_example.yaml (NEW)
• kleene/lib/guides/migration-v2.md (NEW)
• kleene/lib/guides/best-practices.md (NEW)
• kleene/lib/framework/core.md (improvisation clarification)

Acceptance Criteria

• Improvisation nodes reported correctly (not "unreachable")
• All new schema elements validated
• Templates demonstrate all features without errors
• Migration guide successfully applied to test scenarios
• Best practices document covers common patterns