zalbot/prd.md

Product Requirements Document: Dynamic Encounters and Goal Registration

1. Overview

The Mardonar Encounter Engine is a Discord-native, LLM-driven D&D encounter system. Currently, encounters rely on static specs with a predefined list of goals. If player actions diverge significantly from the spec's options, the LLM has to force an awkward resolution or ignore the player's creative agency.

This document defines the requirements for a new Dynamic Goal Registration mechanic. This feature enables the LLM to register custom goals on the fly during play. It also outlines three updated encounter specs showcasing increased versatility and randomizable elements.

---

2. Dynamic Goal Registration Mechanic

2.1 User Experience / Gameplay Flow

1. The encounter starts with 2–3 static base goals.
2. Players take an unexpected or highly creative action (e.g., instead of fighting or running, they bribe a hostile NPC and invite them to a heist).
3. The LLM detects that the current predefined goals are unrealistic or do not match the player's direction.
4. The LLM calls the goal_register tool to define a new goal with a custom ID, description, and status (primary vs. secondary).
5. The bot acknowledges the new goal in the session logs.
6. For all subsequent turns, the system prompt includes this newly registered goal under <hidden_goals>.
7. Once the conditions are met, the LLM resolves the encounter using the custom outcomeId via the encounter_resolve tool.
8. The ending embed in Discord displays the custom goal's description.

2.2 System Architecture & Integration

sequenceDiagram
    participant LLM as LLM (Gemma)
    participant Dispatcher as Tool Dispatcher
    participant Registry as Redis Session Manager
    participant PromptBuilder as Prompt Builder

    LLM->>Dispatcher: goal_register(id, label, isPrimary, reason)
    Dispatcher->>Registry: Update SessionState.spec.goals
    Registry-->>Dispatcher: Success
    Dispatcher-->>LLM: Confirm tool result (system message)
    Note over LLM, PromptBuilder: Next message turn starts...
    PromptBuilder->>Registry: Get SessionState
    Registry-->>PromptBuilder: SessionState (with new goal)
    PromptBuilder->>LLM: Injected System Prompt (contains new goal in <hidden_goals>)

2.3 Technical Specifications

A. Tool: goal_register

• Name: goal_register
• File Location: src/harness/tools/goalRegister.ts
• Arguments:
  • id (string): Unique kebab-case ID (e.g., bribe_and_recruit). Must match regex ^[a-z0-9-_]+$.
  • label (string): Precise description of the trigger conditions.
  • isPrimary (boolean): Whether it is a primary driver or a secondary fallback.
  • reason (string): Justification for the on-the-fly goal registration (used for logging and debugging).
• Behavior:
  • Auto-prefixes the goal ID with dynamic_ (if not already present) to separate custom runtime goals from spec goals.
  • Validates that the goal ID matches the regex ^[a-z0-9-_]+$ and doesn't conflict with existing goals.
  • Enforces a cap of at most 2 dynamic goals per session to prevent infinite loop goal creation.
  • Enforces a cap of at most 20 messages in the session history before blocking any new goal registrations, ensuring the encounter winds down.
  • Updates the active SessionState in Redis, appending the new goal to spec.goals.primary (if isPrimary is true) or spec.goals.secondary.
  • Returns a system message confirmation: [TOOL] New hidden goal registered on the fly: <finalId> - <label>.

B. Prompt Assembly

• No changes to promptBuilder.ts are required, as it already maps over spec.goals.primary and spec.goals.secondary. By mutating the session's copies of these arrays, the prompt builder automatically picks them up for subsequent LLM turns.

C. Resolution Integration

• resolution.ts already handles unregistered outcomeIds gracefully, but with this change, the newly registered goal is present in spec.goals, allowing it to find the goal and show its description text as the "Outcome" field.

---

3. Versatile Encounter Specs

The following specs demonstrate the use of deep randomization combined with dynamic goal generation.

3.1 "The Silt Leak" (mardonar-silt-leak-005)

• Location: Lower Silt District sewer junction.
• Base Goals:
  • leak_patched: Seal the pipeline directly using tools or magic (DC 13).
  • refinery_sabotaged: Force a shutdown at the release valve with community help.
  • district_evacuated: Give up on containment and prioritize fleeing safely.
• Randomizable Fields:
  • leak_substance: Spills either Caustic Rust-Blight Silt (corrodes gear), Sleeping Ether-Vapor (induces sleep/exhaustion), or Wild-Magic Slurry (magic surges).
  • leak_complication: Random blockage (e.g. mutated_silt_rats nesting in the pipes, a corroded_lock on the manual valve, or a greedy_scavenger holding the master key).
• Dynamic Goal Trigger: If players use magic to freeze or transmute the pipes, the LLM registers a new containment method outcome.

3.2 "The Velvet Quill Auction" (mardonar-velvet-auction-006)

• Location: Hidden lounge in the Velvet Quill parlor.
• Base Goals:
  • artifact_stolen: Steal the item from the vault or target’s pocket.
  • fake_swapped: Replace the item with a forged replica during a distraction.
  • brawl_outbreak: Force a chaotic combat, resulting in a blind grab for the item.
• Randomizable Fields:
  • auction_item: Ancient Mawfang Bloodstone, Consortium Black Book, or Fossilized Phase-Spider Egg.
  • buyer_leverage: Karr's secret vulnerability (e.g. superstitious, heavy_drinker, or impostor who is actually broke).
• Dynamic Goal Trigger: If players manipulate the bidding process to ruin the rival financially or get him arrested, the LLM registers an economic victory outcome.

3.3 "The Whispering Stone" (mardonar-whispering-stone-007)

• Location: Misty road near Stormscar Peak.
• Base Goals:
  • spirit_calmed: Calm the spectral captain using history or oaths.
  • ward_restored: Repair the runic stone before the frost barrier collapses.
  • spirit_destroyed: Banish the ghost in combat, fracturing the stone.
• Randomizable Fields:
  • spectral_origin: The spirit is either a Shattered Vanguard Captain, a Terrified Child Acolyte, or a Corrupted Witch Hunter.
  • frost_hazard: Extreme environment (e.g. sapping_cold draining spells, ice_shards area damage, or misty_mirroring clones).
• Dynamic Goal Trigger: If players use emotional/ritual containment to siphon the spirit's sorrow into a vessel, the LLM registers a binding outcome.

---

4. Acceptance Criteria

1. Verification of goal_register tool registration: The tool must be recognized by VALID_TOOL_NAMES and listed in the <tool_contract> system prompt.
2. Session Persistence: When the tool is called, the Redis state must be successfully updated.
3. Goal Recognition: In subsequent LLM calls, the dynamically generated goal must be present in the system prompt <hidden_goals> list.
4. Resolution Verification: The encounter can be successfully resolved with the new custom outcome ID, producing a Discord embed that lists the custom goal's description.
5. Robust Tests: Unit tests must cover the tool handler, validation of arguments (e.g., regex checks on id), and the updates to the session state.