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

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 21 — Joint Briefing	Template instantiation coordination, cross-template triangles, save/load flow	sprint	archived	21	joint

Sprint 21: Instantiate — Joint Coordination

Goal: The template system becomes executable — templates spawn NPCs, assign triangles, and place them in world space; cross-template triangles link social sites; the client gains save/load game flow; and the generator pipeline gets its architectural design.

Pre-Sprint Decisions

No blocking pre-sprint decisions are required. All selected implementation tickets have their upstream decisions confirmed.

Decision	Status	Impact
D-025 (social site as atomic template unit)	Confirmed	Server #159/#166/#161 schema and instantiation shapes
D-024 (NPC 10-axis model, 2 triangles minimum per template, 1 cross-template)	Confirmed	Server #108/#109 triangle requirements
D-087 (v0.1 triangle config: 3 active forks, 2 passive tensions)	Confirmed	#108 must produce triangle types consistent with T1-T5 fork taxonomy
D-089 (self-contained forks, no cross-triangle cascade)	Confirmed	#108 cross-template triangle uses reference links, not shared state
D-085 (per-game save directories)	Confirmed	Client #257 save/load flow writes to user://saves/<game-id>/
D-020 (Godot = pure renderer)	Confirmed	Client #257 never constructs save data — sends command, receives file bytes
D-059 (fog: five layers, shader-based)	Confirmed	Visual #564 tuning target — alpha values must match D-059 layer specs
D-066 (dual-scale grid, 6-8 sim tile fog gradient)	Confirmed	Visual #564 must not alter CLEAR_THRESHOLD/PERIPHERAL_LOW constants that define gradient width

One open question to monitor:

• Q-036 (district skeleton as generator output) — actively being resolved in #562 this sprint. Resolution will gate #144 (Chunk generation system) and shape the Sprint 22 map pipeline tickets. SI will create follow-up tickets once #562 closes.

Planning Ticket

#	Title	Team	Agents
#562	Generator architecture workshop — district/block/chunk pipeline	planning	Gestalt, Tyre, Miri, Araminta, Nigel, Qatux, SI

#562 — Generator architecture workshop

Workshop brief: docs/workshops/generator-architecture/workshop-brief.md

Purpose: Establish the top-down procedural generator pipeline architecture — from geography down to individual chunk fill — that will power the 300-world model. The v0.1 Transit District is hand-authored; this workshop defines what the generator must be able to reproduce and what stub interfaces v0.1 must leave behind.

Context documents to read before the discussion:

• decisions/content.md — D-025 (social site template as atomic unit)
• decisions/scope.md — D-012 (chunk-based map system), D-036 (Sova as v0.1 setting)
• decisions/questions.md — Q-036 (district skeleton as generator output), Q-037 (generator pipeline phases), Q-039 (gate topology generation)
• docs/design/sova-station-profile.md — district types and 6-district layout
• docs/design/spatial-layout-terminal-v01.md, docs/design/spatial-layout-bar-v01.md — hand-authored chunk cluster examples
• decisions/architecture.md — D-093/D-094 (Sova spatial hierarchy: chunk/block/district naming and sizes)

Three rounds:

1. Domain Inventory — each participant states what their domain requires from the generator (Gestalt: gameplay loop guarantees; Tyre: technical constraints on chunk size and hierarchy depth; Miri: cultural/economic variation inputs for 300 worlds; Araminta: visual coherence constraints on chunk fill and sub-chunk quarter system; Nigel: variation and replayability guarantees).
2. Pipeline Proposals — propose pipeline stages, name the spatial hierarchy levels with tile dimensions, describe the district skeleton data structure.
3. Convergence — resolve conflicts, lock spatial hierarchy, define district skeleton output format, set v0.1/generator boundary, draft D-record.

Required outputs:

• D-record in decisions/architecture.md: pipeline stages, spatial hierarchy, sub-chunk quarter rules, multi-block reservation protocol, district skeleton data structure, v0.1/generator boundary
• Resolution of Q-036 (district skeleton as atomic output — yes/no + formal definition)
• Resolution of Q-037 scope (which phases land in which version window)
• Follow-up implementation tickets: chunk data structure update (#143), district skeleton schema, zoning pass stub, block generation stub

SI role in this workshop: Create follow-up tickets from the D-record outputs and assign to Sprint 22 candidates. Update Q-036 and Q-037 status in decisions/questions.md.

Sprint Completion Proof

The sprint is done when all of the following are observable:

1. Template instantiation pipeline end-to-end: Load a Tier 2 YAML from server/data/templates/, call the instantiation engine, assert NPCs spawn with correct roles, TemplateOwnership set, and 2+ TriangleState components generated. cargo test -p server -- instantiation passes.

2. Cross-template triangle produced: A test world with two instantiated templates (logistics hub + bar) generates exactly 1 cross-template TriangleState with role assignments spanning both templates. cargo test -p server -- cross_template_triangle passes.

3. Triangle validation catches bad inputs: Unit tests confirm that a triangle failing conflict viability, relationship coherence, or interest divergence returns a typed ValidationError, not a panic.

4. Save/load round-trip works end-to-end: F5 in-game writes a quicksave file to user://saves/<game-id>/quicksave.sav. F6 reloads it. Player position and NPC state (including open doors from #246) match the save. make ci-client passes.

5. Environmental interaction: A Door entity in a test world toggles walkability on player interaction. An Examinable entity returns examine text. Door state survives a save/load round-trip (open_doors persists in SaveStateV1).

6. Error handling does not crash: Sending a malformed IPC message mid-session produces a structured SimError response and leaves the server running. Integration test asserts this.

7. Fog shader tuned: Fog Theater gauntlet room — entities in peripheral zone are visibly dimmed but not opaque; deep fog shows a readable zone temperature tint; vision cone edge is soft. make ci-client passes.

8. Generator architecture decided: #562 closes with a confirmed D-record, Q-036 marked resolved, Q-037 scope defined. SI creates Sprint 22 candidate tickets for the chunk/district pipeline implementation.

Test Plan Alignment (D-030)

Sprint 21 is Phase 3+ territory. The template instantiation system introduces the first simulation structures that compose content from YAML definitions into live ECS entities.

Ticket	Test scope	Priority
#159	Unit: YAML round-trip, full Tier 2 document	High
#166	Unit: spawn + TemplateOwnership, TemplateReferenceMap entries	High
#161	Integration: YAML → instantiation engine → ECS entities + triangles	High
#108	Unit: cross-template role assignment, reference link creation	High
#109	Unit: all three validation failure modes + passing case	High
#85	Integration: malformed input → SimError, server survives	High
#246	Unit: Door walkability toggle, examine text return	High
#257	End-to-end: F5 save → F6 load → state match	High
#561	Regression: make ci-client passes at new file path	Medium
#564	Visual: Fog Theater gauntlet room manual check	High
#274	Regression: make ci passes with scripts at new paths	High

Cross-Team Integration Points

Server ticket	Client dependency	Notes
#246 (open_doors in SaveStateV1)	#257 (save/load round-trip)	Server must add open_doors: Vec<StableId> to save struct before client can verify state restored correctly
#85 (SimError message type)	#257 (loading screen)	Loading screen should handle SimError gracefully — show error state, not spinner forever

Planning ticket	Downstream impact	Notes
#562 (generator architecture)	#143, #144 (chunk system)	D-record output gates Sprint 22 chunk pipeline work

The #246/#257 dependency is soft — client can stub the door state verification in save/load tests until #246 lands.

Deferred to Sprint 22

Natural Sprint 22 candidates once this sprint's foundation lands:

• #155 (Hand-crafted location authoring) — build the v0.1 Transit District locations in Godot tilemap; requires #153 (done) and the district topology from that D-record
• #188 (Triangle instantiation in v0.1 content) — wire the 5 v0.1 triangles into the instantiation engine; requires #161
• #162 (Storyteller module activation) — draw Tier 1 modules from pool at game start; requires #161
• #143 (Chunk data structure) — blocked until #562 workshop defines the spatial hierarchy
• #176 (NPC pool generation: flat/mundane/entangled ratio) — requires #161 instantiation engine
• Generator pipeline tickets — created by SI from #562 D-record outputs