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

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 18 — Joint Briefing	Examine mechanic integration, knowledge graph wire format, NPC vision coordination	sprint	archived	18	joint

Sprint 18: Touch — Joint Tasks

Goal: The player can examine entities and objects to generate character-filtered observations; NPCs detect and react when watched; social actions propagate through the relationship graph; minimap renders POIs on the client.

Pre-Sprint

No blocking decisions required before implementation starts. All architectural decisions for Sprint 18 scope are confirmed.

Decision	Status	Impact
D-011 (NPCs use same LOS system)	Confirmed	#115 (NPC vision) — no new LOS mechanism needed
D-026 (simulation tiers)	Confirmed	#95 (background state machines) — BackgroundSim marker exists
D-041 (knowledge graph data model)	Confirmed	#242 (examine), #264 (journal display) — KG is the output format
D-062 (invisible locked options)	Confirmed	#174 (dialogue UI audit) — no grayed-out options anywhere
D-035 Amendment Sprint 15 (NPC-scoped line IDs)	Confirmed	#544 (ID design) extends this for auto-generated NPCs
Q-028 (collision-resistant line IDs)	Open	#544 resolves this — copy team, week 1

Cross-Team Integration Points

Server → Client wire format additions (week 1 coordination)

Two new snapshot fields must be agreed before client implementation begins:

New field	Server ticket	Client ticket	Format notes
examine_result	#242	#174	{entity_id, text, confidence} or null — character-filtered observation text
player_knowledge	#256 (stub) / #242	#264	Partial KG dump: {entities: [{id, name, confidence, source, state, last_tick}], facts: [...]}
poi_list	#148/#149 (done)	#151	Already in snapshot from Sprint 17 — verify field name with server

Action: server team (Tyre/Dudley) and client team (Stig) align on field names and wire format on day 1. No code needed — just agreed field names written to a .tmp/ file or directly into server/src/bridge/types.rs as stub structs.

Server → Copy dependency

Server ticket	Copy output	Integration
#91 (skill system)	#544 (ID scheme)	Auto-generated NPC skills will need line IDs once the NPC pool is large. ID scheme must work for skill-bearing generated NPCs.
#115 (NPC vision)	#248 (pressure framework)	Awareness events from #244 drive exposure_pressure in #248 — copy team's monologue lines with mood: [anxious] are the output surface.

Copy → Server dependency

Copy output	Server ticket	Integration
#544 (ID scheme decision)	Content registry	Server team cannot implement collision-resistant registry until scheme is decided. Sprint 19 work.
#158 (drama module schema)	Storyteller activation	Schema design constrains the storyteller module interface. Server team should review #158 output before storyteller implementation begins.

Sprint Completion Proof

Sprint 18 is DONE when:

1. Examine fires and is character-filtered — Player uses Examine on an NPC at close range. The client displays a short observation text. The smuggler and detective receive different text for the same NPC — same entity, different perspective.
2. NPC notices the player — An NPC with the player in its LOS for ≥N consecutive ticks changes behavior: route deviation, posture shift, or tell state update. The player can observe this response.
3. Social ripple is observable — Player action toward NPC A (e.g., a trust-positive dialogue) causes a measurable trust delta on NPC B (second-order relationship). Verify via server state inspection or the WRONG button (F12) snapshot.
4. Tell states wire to snapshot — Active-tier NPCs with Major secrets show Nervous or Guarded tell in the ObserverSnapshot. The client renders this (monologue trigger or entity tint — verify whichever is wired).
5. Minimap renders POIs — Discovered POIs appear as dots/arrows on the insert minimap overlay. Player position is centered. Minimap is present when at least one POI has been discovered.
6. Journal panel opens — Player opens journal panel. At least one KG fact entry is visible with confidence level, source, and game-time timestamp.
7. Background NPCs tick — A Background-tier NPC's schedule, mood, relationship, and job state visibly change over game-time (verify via WRONG button or server log). Tick rate is once per game-minute (10 ticks per D-031).
8. Skill system exists — Generated NPCs have a SkillSet component. At least one NPC is spawned with combat_trained skill, resulting in a CombatCapability marker component attached.
9. Save data model stubs round-trip — A SaveStateV1 struct serializes and deserializes without data loss. Test coverage confirms roundtrip fidelity for: entity positions, KG entries, relationship graph, simulation tick.
10. Line ID scheme is decided — Q-028 is resolved. A decision record (D-NNN) exists in decisions/content.md. The scheme is documented clearly enough for a writer to apply it immediately.

Test Plan (D-030 alignment)

Sprint 18 is in the integration testing phase (ongoing from Sprint 3 per D-030). The gauntlet infrastructure from Sprint 17 is the primary test harness for server-side verification.

Ticket	Test approach
#242 (examine)	Unit test: process_examine_interaction with mock KG → confirm character-filtered output differs between smuggler and detective KG states. Integration test: examine verb from player action → KG entry written via event queue.
#244 (NPC awareness)	Unit test: NPC with player in LOS for N ticks → PlayerAwareness component threshold crossed → routine deviation fired.
#248 (pressure framework)	Unit test: high awareness events → exposure_pressure rises. Integration: pressure visible in snapshot HUD data.
#249 (social propagation)	Unit test: trust delta +5 to NPC A → NPC B (strong relationship to A) receives delta ~+2. Cycle test: A→B→A propagation terminates cleanly.
#337 (tell state wiring)	Integration test: TellCategory::Nervous for NPC with Major secret + stress past midpoint → confirmed in snapshot entities[].tell_state.
#91 (skill system)	Unit test: NPC with combat_trained skill in SkillSet → CombatCapability component present after spawn. Unit test: NPC without combat_trained → no CombatCapability.
#115 (NPC vision)	Unit test: NPC placed adjacent to player (within LOS, no walls) → NpcVisionState contains player StableId. Wall-blocked: player not visible.
#256 (save state)	Unit test: serialize SaveStateV1 with known state → deserialize → all fields match. Round-trip for KnowledgeGraph (already serializable).
#95 (background ticks)	Unit test: NPC with BackgroundSim, advance 10 ticks → schedule state machine advances. Unit test: mood drift toward neutral after 10 ticks.
#151 (minimap)	Manual: POI discovered → minimap dot appears. Distant POI: directional arrow appears at minimap border.
#174 (dialogue UI)	Manual: examine result appears as overlay, auto-dismisses. Dialogue options confirmed: no locked/grayed options visible. Confrontation option in italic voice.
#264 (journal)	Manual: journal panel opens, KG facts listed with correct metadata. Contradicted facts visually distinct.
#544 (ID scheme)	Decision review: scheme handles all four population categories (hand-authored, role-based, generated unique, generated shared).
#158 (drama module schema)	Schema review: stub smuggling_ring_v0_1.yaml validates against drama_module.schema.yaml.

Teams

Team	Branch	Agents	Tickets
server	server	Dudley, Tyre, Hoshe	#242, #244, #248, #249, #337, #91, #115, #256, #95
client	client	Stig, Tyre, Hoshe	#151, #174, #264
copy	copy	Mellanie, Paula, Gestalt	#544, #158