settled-reach/docs/sprints/sprint-7/joint.md

Sprint 7: Talk — Joint Integration

Goal: Complete interaction UI layer and activate basic dialogue system with NPC conversations.

Teams: Server, Client, Copy, Audio Agents: All implementation agents (Dudley, Stig, Tyre, Hoshe, Mellanie, Paula, Gestalt, Inigo)

Sprint Overview

Sprint 7 is the completion sprint for Sprint 6's unfinished UI work (6 carry-over tickets) and the foundation sprint for the dialogue system. Sprint 1-5 built the simulation, bridge, rendering, content loading, and FRIEND NPCs. Sprint 6 delivered movement stances, tile occupancy, verbs, and inventory mechanics (server-side). Sprint 7 completes the UI layer that makes those mechanics visible and playable, and begins dialogue system implementation.

After Sprint 7, players can:

• See cursor states change based on hover target (entity/object/world)
• Interact with entities via vertical lists and world radial menu
• See fog breathe with animated noise and recognize entities through cognitive delay
• View inventory and stance in HUD
• Begin basic NPC conversations through the dialogue box

Team Distribution

Team	Ticket Count	Load
Server	5 tickets	Medium (cognitive delay, line pool spec, YAML loader, interaction memory schema, eavesdrop)
Client	8 tickets	HEAVY (6 Sprint 6 carry-overs + 2 new; fog shader is major rewrite)
Copy	1 ticket	Light (archetype evidence spec, design document)
Audio	1 ticket	Light (6 audio assets for interaction states)

Total: 15 tickets

Pre-Sprint Requirements

No blocking decisions or schema work. All Sprint 6 server work is complete:

• ObserverSnapshot v6 (player_stance, player_inventory) — done (#449)
• Two-phase verb computation — done (#422)
• Stance system — done (#417)
• Smuggler inventory — done (#424)

Sprint 7 can proceed immediately.

Critical Path

Server track (dialogue foundation):
#308 (line pool spec) → #326 (YAML loader) → enables future #305 (dialogue system)

Server track (fog cognitive delay):
#423 (cognitive delay) → Client #431 (fog entity viz)

Client track (UI carry-overs):
#429 (cursor states) → #432 (interaction list)
#430 (fog shader rebuild) → #431 (fog entity viz)

Client track (parallel standalone):
#433 (world radial menu)
#438 (inventory UI) — wire data from ObserverSnapshot v6
#439 (stance UI) — wire data from ObserverSnapshot v6
#434 (dialogue box) — foundation for future dialogue system

Copy track:
#443 (evidence spec) — standalone design doc

Audio track:
#440 (6 audio assets) — supports client UI (#429, #431, #433, #434)

Critical integration point: Server #423 (cognitive delay) must land before client #431 (fog entity visualization) can integrate. Client #430 (fog shader rebuild) is also a blocker for #431.

Largest risk: Client #430 (fog shader rebuild) is a complete rewrite of the fog rendering system. High risk of performance regressions or visual artifacts. Requires early performance testing.

Cross-Team Integration Points

Server → Client: Cognitive delay data (#423 → #431)

Server deliverable (#423): Add pending_recognitions field to ObserverSnapshot:

• List of entities in fog that are in recognition delay state
• Data per pending entity: approximate position (±0.5 tile drift), delay_remaining_ticks, trigger_type (normal/urgent)
• Recognition transitions: grey blob → recognized (with color + silhouette) when delay expires

Client consumer (#431): Fog entity visualization reads pending_recognitions and renders:

• Unrecognized: grey blob #555566, no silhouette, breathing animation
• Recognition transition: grey → D-033 color + faint silhouette over ~0.3s
• Recognized: full D-033 color glow + silhouette feature + breathing pulse

Timeline: Server #423 should land mid-sprint (after #308, parallel to #326). Client #431 is blocked by both #423 (server) and #430 (client fog shader).

Coordination: Dudley (server) defines wire format for pending_recognitions. Stig (client) consumes format and renders fog entities per Araminta's D-059/D-060 spec.

Server → Client: Line pool spec (#308 → future dialogue work)

Server deliverable (#308): Line pool format specification document at docs/architecture/line-pool-format.md:

• YAML structure for dialogue.yaml and monologue.yaml files
• Tag definitions (access, trust, situation, topic, mood, character, trigger, prerequisite)
• File naming conventions and directory structure
• ID format: {template}_{d|m|e}_{###}

No direct client dependency in Sprint 7. This spec enables:

• Server #326 (YAML loader) — Sprint 7
• Copy team line authoring — Sprint 8+
• Server #305 (dialogue selection pipeline) — Sprint 8+

Timeline: Server #308 should land early (week 1) to unblock #326 and enable copy team preview of authoring workflow.

Client → Audio: UI interaction sounds (#429, #431, #433, #434 → #440)

Client deliverables: Four UI systems that trigger audio:

• #429 (cursor states): cursor hover on entity → play cursor_hover.ogg
• #431 (fog recognition): entity recognition complete → play fog_recognition.ogg
• #433 (radial menu), #438 (inventory), #439 (stance): insert UI opens → play implant_open.ogg
• #434 (dialogue box): dialogue starts → ambient dip (-6dB to -8dB)

Audio deliverable (#440): 6 audio assets (5 .ogg files + 1 ambient dip implementation spec)

Timeline: Audio assets can be authored in parallel with client UI work. Integration happens when client tickets land — Stig adds audio calls to UI event handlers.

Coordination: Inigo (audio) delivers assets to client/audio/ directory. Stig (client) integrates audio calls into cursor state machine, fog rendering, radial menu, dialogue box.

Sprint Completion Proof

At the end of Sprint 7, the following must be observable in-game:

Cursor and Interaction UI

1. Cursor states work: Hover over empty tile → default ticks. Hover over NPC → entity hover (ticks expand, D-033 color). Hover over object → X-shape grey cursor. All transitions 150ms smooth.
2. Entity interaction list renders: Hover over NPC with multiple verbs → vertical list appears (2-4 options max), anchored to entity, insert-styled. Click verb → PlayerAction::Interact sent to server.
3. World radial menu works: Right-click world tile → radial menu opens with 2 spokes (Observe + Insert). Drag-release or click-click to select. Renders on z-layer 6.
4. Audio feedback: Cursor hover plays subtle tick/ping. Radial menu open plays implant hum.

Fog System

5. Fog shader renders: Launch game, observe 5-layer fog system:
   • Clear cone with soft gradient edge (no hard line)
   • Light fog (peripheral) with animated Perlin noise (8-10s cycle), desaturated colors
   • Deep fog (previously explored) with zone temperature tint, slower noise (15-20s cycle)
   • Fog breathes — noise animation cycles, fog feels alive
6. Fog entity visualization works:
   • Sound events: thin concentric expanding rings (sonar-style), white-blue, fade over 1.5s
   • Unrecognized entity: grey blob #555566, no silhouette, breathing animation
   • Cognitive delay: grey blob → D-033 color + silhouette transition over ~0.3s
   • Recognized entity: full D-033 color glow + faint silhouette + breathing pulse + ±0.5 tile position drift
7. Cognitive delay timing: Observe sound in fog → grey blob appears → monologue fires ("Those footsteps... that's Kael's walk") → 0.6s later → blob transitions to green (known/friendly) with vest silhouette. Timing feels like character recognition, not UI update.
8. Audio feedback: Fog recognition plays warm organic chime when transition completes.

HUD and Inventory

9. Inventory UI renders: Smuggler character → bottom-right 3x3 grid appears. Icons for 3 items (manifest copy, access token, comm log). Detective character → 2 items (or empty if no items carried). Press 1-9 keys → item selection feedback (highlight border).
10. Stance toggle UI renders: Top-left or top-right stance indicator shows current stance (Sprint/Walk/Careful/Crouch). Press C → stance cycles → indicator updates. Visual feedback: stance name + movement speed indication.
11. Audio feedback: Inventory or stance UI opens → implant activation hum.

Dialogue System Foundation

12. Dialogue box renders: Bottom screen, max 20% height, left-aligned. No portrait. Layout: NPC speech top, player response options below. Max 3 options visible. Test with mock NPC dialogue data (hardcoded test strings).
13. Walk-away mechanic works: During dialogue, press WASD → dialogue fades over 300ms, no close button required.
14. Monologue above dialogue: Monologue floats above dialogue box (z-layer 7). Both visible simultaneously — character can think one thing while NPC says another.
15. Audio feedback: Dialogue starts → ambient audio dips -6dB to -8dB (background recedes). Dialogue ends → ambient returns to 0dB.

Server Systems

16. Cognitive delay system active: Server logs show CognitiveDelay component tracking pending recognitions. KnowledgeEvent emitted after delay expires (0.6s base, 0.3s urgent). ObserverSnapshot.pending_recognitions populated correctly.
17. Line pool spec complete: docs/architecture/line-pool-format.md exists and is readable by copy team. YAML structure documented, tag definitions clear, file conventions specified.
18. YAML loader functional: Server loads dialogue.yaml and monologue.yaml files at startup. Hot-reload works (file change → server reloads pool). Query API: query_lines(access, situation, topic, mood) returns filtered Vec.
19. InteractionMemory schema designed: docs/architecture/interaction-memory-schema.md exists. FactId format, interaction state enum, metadata fields documented. Aligns with D-041 KnowledgeGraph BTreeMap pattern.
20. ListeningFocus implemented: Server tracks stationary_ticks. After 30 ticks (~3s) of being stationary, eavesdrop positioning bonus applies (boost sound perception range).

Integration

21. All systems compose: Cursor + fog + interaction list + radial menu + inventory + stance + dialogue all work simultaneously. No system breaks another.
22. No performance regressions: Fog shader <1ms/frame. Client framerate stable at 60 FPS. Server tick budget <100ms (Active tier at 10 tps per D-026).
23. Audio integration complete: All 6 interaction sounds play at correct trigger points. Ambient dip works for dialogue (no audio glitches or clipping).

Validation Tests

Simulation (server):

# Cognitive delay system tests
cargo test simulation::perception::cognitive_delay

# Line pool loader tests
cargo test content::line_pool

# ListeningFocus tests
cargo test simulation::interaction::listening_focus

Client rendering:

# Godot client launches without errors
cd client && godot --headless --quit

# Fog shader compilation (manual test: launch game, observe fog rendering with no console errors)
# Performance test: Godot profiler shows fog rendering <1ms/frame

Audio integration:

# Manual test: trigger each audio event, verify sound plays
# - Cursor hover on entity
# - Fog recognition complete
# - Radial menu open
# - Dialogue start (ambient dip)

Test Plan Alignment (D-030)

Sprint 7 is in Phase 3 (simulation depth) with continued Phase 2 (integration) coverage.

Key test requirements:

Phase 2 (integration):

• Cognitive delay pipeline: perception event → cognitive delay → KnowledgeEvent → ObserverSnapshot.pending_recognitions → client fog entity rendering
• UI event flow: cursor hover → audio trigger, radial menu open → audio trigger, dialogue start → ambient dip

Phase 3 (simulation depth):

• Cognitive delay timing: 0.6s base, 0.3s urgent (verify tick counts at 10 tps)
• Line pool filtering: 4-layer filtering (access → situation → topic/mood → selection)
• ListeningFocus: stationary_ticks increments correctly, resets on movement, eavesdrop bonus applies at threshold

Hoshe's involvement: QA review on #430 (fog shader — large rewrite, performance regression risk), #423 (cognitive delay — new perception pipeline component), #326 (YAML loader — hot-reload complexity).

Integration Risks

Risk: Fog shader rebuild (#430) is a complete rewrite. High risk of performance regressions (noise shaders are expensive) or visual artifacts (layer blending, z-fighting).

Mitigation: Stig implements #430 on feature branch, tests in isolation before merging. Performance target: <1ms/frame (monitor with Godot profiler). If performance regresses, scale back noise animation complexity (reduce cycle count, simplify Perlin shader, or use pre-baked noise texture). Visual artifacts: test z-layer ordering carefully (fog on Layer 5, entities on Layer 3, fog entities between Layer 5 and Layer 6).

Risk: Cognitive delay system (#423) introduces new timing-sensitive logic. Risk of edge cases (e.g., entity moves out of fog during delay, recognition fires for wrong entity).

Mitigation: Dudley adds integration tests for cognitive delay edge cases. Verify: delay cancellation on entity exit, delay restart on re-observation, correct entity mapping in pending_recognitions. Use CauseChain (D-030 sub-decision #4) for debugging provenance.

Risk: Client has 8 tickets (6 carry-overs + 2 new), making it the heaviest client sprint. High ticket count = coordination overhead and potential for incomplete work.

Mitigation: Prioritize critical path: #429 (cursor) → #432 (interaction list), #430 (fog shader) → #431 (fog entity viz). Standalone tickets (#433 radial menu, #438 inventory, #439 stance, #434 dialogue box) can be deferred to Sprint 8 if time is constrained. Fog shader (#430) is the largest technical risk — if it proves too complex, scale back or defer #431.

Risk: YAML loader hot-reload (#326) adds file watching complexity. Risk of file watch bugs (platform-specific, permission issues, polling overhead).

Mitigation: Use notify crate (well-tested Rust file watcher) or simple timestamp polling. Hot-reload is dev-only feature (not production runtime), so failures are non-critical. Fall back to manual restart if hot-reload is unstable.

Risk: Audio integration (#440) across 4 client systems (cursor, fog, radial, dialogue). Risk of audio timing bugs (sounds cut off, overlap incorrectly, or don't play).

Mitigation: Inigo delivers audio assets with clear trigger point documentation. Stig tests each audio trigger in isolation before integration. Use Godot AudioManager autoload (if it exists) for centralized audio management. Ambient dip uses AudioBus volume control (declarative, less error-prone than manual AudioStreamPlayer management).

Definition of Done

Sprint 7 is complete when:

1. All 15 tickets marked done in database
2. All server code committed to server branch and tested
3. All client code committed to client branch and tested
4. All copy docs committed to copy branch
5. All audio assets committed to audio branch
6. PRs created for all four teams
7. Sprint completion proof checklist verified (all 23 observable criteria met)
8. Team Leader reviews in-game playtest: cursor states, fog shader, interaction UI, inventory/stance HUD, dialogue box foundation all working without desyncs, performance regressions, or audio glitches

PR Coordination

Four team PRs will be created:

1. Server team PR:

   • Branch: server
   • Scope: Cognitive delay system, line pool spec, YAML loader, interaction memory schema, ListeningFocus
   • Review focus: Cognitive delay timing accuracy, line pool spec clarity for copy team, YAML loader hot-reload stability, interaction memory schema alignment with D-041

2. Client team PR:

   • Branch: client
   • Scope: Cursor states, fog shader rebuild, entity interaction list, world radial menu, inventory UI, stance UI, fog entity visualization, dialogue box
   • Review focus: Fog shader performance (<1ms/frame), cursor state transitions (smooth 150ms), UI z-layer correctness, audio integration (no glitches)

3. Copy team PR:

   • Branch: copy
   • Scope: Archetype evidence presentation spec
   • Review focus: Spec clarity, archetype differentiation (detective institutional vs smuggler personal), contradiction presentation design

4. Audio team PR:

   • Branch: audio
   • Scope: 6 interaction audio assets
   • Review focus: Audio aesthetic alignment with insert-styled UI, ambient dip implementation correctness, file format compatibility

All PRs target main branch. Server PR should merge first (provides cognitive delay data for client #431). Client, copy, and audio can merge in parallel after server lands.

Notes for Team Leader

Sprint 7 is the UI completion and dialogue foundation sprint. After 6 sprints of simulation and mechanics, this is the sprint where the game becomes visibly playable:

• Cursor states make interaction legible: The cursor tells you what you're looking at before you click. Entity hover (D-033 color + brackets) vs object hover (X-shape grey) vs world (default ticks). Interaction intent is visible.
• Fog breathes: The shader rebuild (D-059) replaces flat fog with animated, knowledge-graph-driven fog. Fog entities pulse, recognized entities glow, sound pings expand. This is asymmetric information made visual.
• HUD is complete: Inventory grid, stance indicator, interaction lists, radial menu. The player can see what they're carrying, how they're moving, what they can do.
• Dialogue box is ready: The foundation for NPC conversations. Sprint 8 will activate the dialogue system; Sprint 7 builds the UI container.

Sprint 7 delivers D-027 criterion #2: "Observed a routine, noticed a deviation, felt compelled to investigate." The fog entity visualization (recognized vs unrecognized), cognitive delay (monologue-driven recognition), and interaction UI (verb lists, radial menu) compose into the observation-investigation loop.

Quality bar: All UI systems must compose without breaking each other. Cursor + fog + interaction + inventory + stance + dialogue running simultaneously with no performance regressions, no z-layer conflicts, no audio glitches. Integration is the success metric.

Sprint 7 is also the heaviest client sprint (8 tickets). If fog shader (#430) proves too complex, scale back or defer. The goal is completion, not perfection — fog can be polished in Sprint 8 if needed.