settled-reach/docs/sprints/sprint-4/server.md

Sprint 4: Feel — Server Tasks

Goal: Content conversion and authoring begins — wiki to YAML, content packs, monologue pool

Branch: server Agents: Dudley (simulation), Tyre (architecture), Hoshe (QA)

New Tickets

#	Title	Priority	Blocked by
#408	YAML content loader Phase 2 — real content loading	high	#387, #388, #389, #390, #391, #398
#387	Create global/enums/ YAML files from D-035	medium	—
#388	Create global/knowledge/entity-attributes.yaml	medium	—
#389	Create pools.yaml for v0.1 seed-time selection	medium	—
#390	Create template YAML files with role slot definitions	medium	—
#391	Create triangle YAML files for 5 v0.1 triangles	medium	—
#394	Seed configuration schema design	medium	—
#403	YAML → RON converter tool	medium	—
#407	Line previewer CLI	medium	—

Use db/connectors/ticket show <id> for full details.

Key Decisions

• decisions/content.md — D-024 (NPC 10-axis model), D-025 (social sites), D-028 (dialogue architecture), D-035 (tag taxonomy)
• decisions/architecture.md — D-020 (IPC protocol), D-026 (simulation tiers), D-030 (testability)
• Workshop outputs: docs/workshops/content-gap-analysis_v0_1/SUMMARY.md

Notes

Content loader Phase 2 (#408):

Content loader was stubbed in Sprint 2-3. Phase 2 extends it to load real content from YAML files populated by copy team's conversion work and the C4-C8 YAML population tickets below.

• What exists:
  • Content directory structure: content/ with full nested hierarchy (Sprint 3, #385)
  • Schema files: content/_schema/*.schema.yaml (Sprint 3, #386)
  • Validation tooling: make validate-content (Sprint 3, #392)
  • Stub loader: likely in server/src/ (check for existing content loading code from Sprint 2-3)
• What to deliver: Extend content loader to read and instantiate real district content, NPC profiles, dialogue pools, templates, triangles. This is the bridge from authored YAML files to runtime ECS entities.
• Blocked by: #387-#391 (YAML population tickets — can't load content that doesn't exist) + #398 (copy team NPC conversion).
• Integration: Feeds NPC ECS entities into simulation. Works with existing server/src/npc/ module (mod.rs, relationships.rs, routine.rs). Likely creates or extends server/src/simulation/content_loader.rs.
• Note: This is NOT an authoring ticket. You're implementing the loader that reads files other people write. The copy team authors content; you make the server consume it.

YAML population tickets (#387-#391):

Five parallel tasks that populate content/global/ and content/campaigns/.../transit/ directories with v0.1 data. These are mechanical data-entry tickets implementing schemas from Sprint 3 and taxonomy from D-035.

All five use existing schema files from content/_schema/ and validate via make validate-content.

#387 (Enums):

• File: content/global/enums/situations.yaml, topics.yaml, moods.yaml, triggers.yaml, access-tiers.yaml, activities.yaml
• Content: 13 situations, 9 topics, 8 moods, 9 triggers, 5 access tiers, activities list (from Gestalt routine format + Miri cultural patterns)
• Source: D-035 appendices, workshop Gap Analysis outputs
• Purpose: These are the canonical enum values referenced by all dialogue and monologue tags

#388 (Entity attributes):

• File: content/global/knowledge/entity-attributes.yaml
• Content: 16 canonical entity attribute keys (14 original from D-024, 4 new, 2 renamed per workshop Appendix A7)
• Format: Machine-readable attribute definitions. All observer→target.
• Purpose: Knowledge graph attribute vocabulary

#389 (Pools):

• File: content/global/pools.yaml or content/campaigns/main/systems/van-maanens-star/stations/sova/pools.yaml (decide per workshop design doc #384)
• Content: v0.1 single-candidate pools: friend_smuggler (kael-davan), friend_detective (sera-venn), bar_regulars, compromised_inspector, primary_contraband
• Purpose: Seed-time selection system. Architecture supports N candidates; v0.1 has 1 each for deterministic testing. v0.2 expands to real pools.

#390 (Templates):

• Files: content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/templates/logistics-hub.yaml, bar.yaml, smuggling-ring.yaml
• Content: 3 social site templates. Each declares named role slots with count ranges, required flags, pool references, triangle constraints.
• Purpose: Template instantiation system (D-025 social sites). NPCs fill roles.

#391 (Triangles):

• Files: content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/triangles/hub-power.yaml, worried-knowledge.yaml, bar-tensions.yaml, worried-partner.yaml, informant-question.yaml
• Content: 5 v0.1 triangles per workshop synthesis. T1 (hub-power, active fork), T2 (worried-knowledge, active fork), T3 (bar-tensions, passive), T4 (worried-partner, active fork), T5 (informant-question, passive).
• Purpose: Atomic units of social intrigue (D-024). Self-contained fork points for storyteller activation.

Seed configuration schema (#394):

Design document (not implementation) for the seed configuration schema. Defines what the randomizer produces at game-start: FRIEND selections, social site population, compromised NPC, contraband type, entanglement overrides.

• Deliverable: docs/architecture/seed-configuration-schema.md design document
• Scope: v0.1 has single-candidate pools but architecture must support N-candidate randomization for v0.2 replayability
• Purpose: This is the handoff contract between "what content authors define" (pools, templates, triangles) and "what the game instantiates" (specific NPCs, specific relationships, specific activated triangles)
• Note: Design doc only. Implementation comes in Sprint 5+.

YAML → RON converter (#403):

Build-time converter tool: reads content YAML, emits RON. Lives in tooling/content-converter/ (create new crate). Runs as make content-ron.

• What exists: tooling/ directory at repo root
• What to deliver: Rust binary crate that parses YAML content files and serializes to RON. v0.1 scope: proof-of-concept for one content type (e.g., NPC profiles or dialogue pools).
• Integration: NOT on critical path — engine consumes YAML in v0.1. RON is future-proofing for runtime performance (RON deserialization is faster than YAML). Build system integration via Makefile target.
• Note: This is infrastructure tooling, not game logic. Parallel work, low priority.

Line previewer CLI (#407):

CLI tool to preview monologue/dialogue line selection for a given game state. Lives in tooling/line-previewer/ (create new crate).

• What exists: tooling/ directory
• What to deliver: Rust CLI that simulates line selection. Input: YAML content files + synthetic game state (character, location, knowledge state, mood, active NPCs). Output: which lines would be selected and why (shows tag matching, prerequisite evaluation, weighted selection).
• Purpose: Authoring tool for copy team. Lets Mellanie/Paula test "does this line trigger when I expect it to?" without running the full game.
• Integration: Reads same YAML schema as content loader. Uses same selection logic (can share code with dialogue/monologue systems or reimplement simplified version). Not part of game runtime — pure tooling.
• Blocked by: #386 (content schema, done) and #392 (validation CLI, done) — needs to parse same YAML format.

Dependency Chain

#387 (enums) → #408 (content loader Phase 2)
#388 (entity attributes) → #408
#389 (pools) → #408
#390 (templates) → #408
#391 (triangles) → #408
#398 (copy: Wiki→YAML NPCs) → #408

#408 (content loader) → real content in-game

#394 (seed schema design doc) → standalone (design only)
#403 (YAML→RON converter) → standalone (future-proofing)
#407 (line previewer CLI) → standalone (authoring tool)

Critical path: #387-#391 + #398 (copy team) all feed into #408. Until #408 lands, the server can't load v0.1 content.

Parallel work: All five YAML population tickets (#387-#391) are independent and can proceed in parallel. #403 and #407 are standalone tooling — not blocking anything.

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server