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

Sprint 17: Tell — Joint Tasks

Goal: NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.

Pre-Sprint: Knowledge Flow & NPC Boundaries Workshop (COMPLETE)

Outcomes: docs/workshops/knowledge-flow-npc-boundaries/workshop-outcomes.md Participants: Tyre (arch), Gestalt (mechanics), Dudley (impl), Paula (narrative), Qatux (docs) Status: Complete. All decisions registered, tickets created.

Decisions Produced

Decision	Topic	Key outcome
D-079	Knowledge Grant Architecture	Compound KnowledgeGrant enum (Fact + Entity), ContentEntityRegistry, grants fire at line selection
D-080	NPC-to-NPC Propagation	Transfer via transfer_npc_knowledge system, trust-gated, confidence capped at KnowsOf
D-081	Unprompted Disclosure	DisclosureCandidates component, trigger gates, three-layer rate limiting, two-stage trait filter
D-082	NPC Information Boundaries MVP	tell_state + disclosure only, pathfinding deferred, Active-tier only
D-083	Contradiction Detection Pipeline	Event-driven at KG write time, ContradictionClaim struct, 600-tick window

Questions Closed

Question	Resolution
Q-024	Gossip timing — conversation system hook confirmed
Q-025	KG memory — not a constraint at current scale, re-evaluate at 200+ Active NPCs
Q-026	Contradiction detection — event-driven at KG write time with ContradictionClaim

Team Lead Decision

Entity grants ship in Sprint 17 (overrides FactId workaround). Compound KnowledgeGrant with Entity variant + ContentEntityRegistry at NPC spawn.

Workshop Tickets Created

7 implementation tickets (#545-#551) under the Knowledge Graph epic, plus #552 (copy team contradiction content). See server briefing for full dependency chain.

Pre-Sprint Decisions

Decision	Who	Status
Workshop Topics 1-5	Tyre, Gestalt, Dudley, Paula	Done — D-079 through D-083
Q-028: Collision-resistant line IDs	Gestalt, Tyre	Open

Cross-Team Integration Points

Server ticket	Client ticket	Integration
#148 POI data model	#263 Time display	POI data feeds future minimap; time data already in snapshot
#232 Protocol versioning	All client	Client must handle version field in messages
#551 Unprompted disclosure	#537 E-Talk UX	Disclosure lines appear in dialogue UI; E-Talk overlay should hint at NPC willingness

Server ticket	Visual ticket	Integration
#148 POI data model	#314 Insert/HUD wireframe	POI categories must match wireframe's display elements

Server ticket	Copy ticket	Integration
#550 Contradiction monologue	#552 Author contradiction lines	Copy authors lines per D-083 spec; server wires them into monologue system

Sprint Completion Proof

Sprint 17 is DONE when:

1. Unprompted disclosure fires — An NPC with high trust and relevant knowledge volunteers information to the player without being asked. The volunteered line appears in the dialogue UI. The player's KnowledgeGraph gains a new fact via knowledge_grant.
2. Trait modifiers reshape delivery — Two NPCs with different personality traits deliver the same base information differently (different mood, different wording or selection weight).
3. Time is visible — The insert HUD shows current game time in a diegetic format. Time advances visibly as ticks pass.
4. POIs exist on the map — Server spawns POI entities with the PointOfInterest component. POIs can be discovered via walking into a location (physical discovery).
5. Protocol version field exists — All messages include a version field. Client logs a warning on version mismatch.
6. E-Talk overlay is informative — The interaction overlay shows NPC name (if known), relationship color, and a dialogue tier hint.
7. Insert wireframe is specified — Both smuggler and detective variants are wireframed with layout, colors, and interaction states documented.
8. Tutorial monologue fires — First-time events (move, fog, sound, NPC proximity) trigger diegetic tutorial lines for both characters.
9. Contradiction detection fires — Location contradiction between ToldBy and DirectObservation sources marks both entries Contradicted. Source-named monologue line triggers. THE FRIEND arc mechanical sequence validates end-to-end.
10. NPC-to-NPC knowledge transfers — NPCs in conversation exchange trust-gated facts. ToldBy source is constructed. Confidence capped at KnowsOf.

Test Plan (D-030 alignment)

Sprint 17 is in the integration testing phase (Sprints 3-4 per D-030):

• #545 + #546: Unit tests for KnowledgeGrant enum serde roundtrip, ContentEntityRegistry resolution, KnowledgeGranted event processing.
• #547 + #550: Integration test — ToldBy entry + DirectObservation at different position within 600-tick window → Contradicted state → monologue fires → relationship shift → amber color.
• #548: Integration test — NPC conversation transfers facts, confidence capped, ToldBy source constructed.
• #549: Unit test — tell_state reads KG for relationship data, falls through to axes for self-knowledge.
• #551 + #172 + #173: Integration test — NPC with specific axis values and KG state triggers unprompted disclosure; trait modifier changes the selected line.
• #148 + #149: Unit tests for POI component CRUD; integration test for discovery event → KG update.
• #232: Unit test for version serialization roundtrip; integration test for version mismatch handling.
• #263: Manual verification — time display updates as simulation advances.
• #537: Manual verification — overlay shows correct NPC data.
• #330: Line preview test — tutorial lines fire on first-time triggers, respect cooldown -1 (fire once).
• #552: Content review — contradiction lines follow cognitive-dissonance-not-accusation tone, name source entity.

Teams

Team	Branch	Agents	Tickets
server	server	Dudley, Tyre, Hoshe	#545, #546, #547, #548, #549, #550, #551, #141, #142, #172, #173, #148, #149, #232
client	client	Stig, Tyre, Hoshe	#263, #537
copy	copy	Mellanie, Paula, Gestalt	#330, #552
visual	visual	Araminta	#314