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

# Sprint 12: Build — Joint / Integration Notes

**Goal:** Lay the production-layer foundations — simulation tier system, sound event pipeline, visual grammar, and knowledge boundary enforcement — and complete all v0.1 copy authoring so content packs, opening hooks, and world-building docs are done.

**Sprint 12 ID:** 12
**Status:** planning (activate with `db/connectors/sprint start`)

---

## Pre-Sprint Decisions

No blocking open decisions. The following decisions are implemented this sprint and should be cross-referenced:

| Decision | Domain | Implementing ticket(s) |
|----------|--------|----------------------|
| D-041 (knowledge graph) | architecture | #138, #139 (KG access control) |
| D-018 (three-range sound) | perception | #124 (server), #125, #126 (client) |
| D-068 (5-bus audio architecture) | architecture | #125 (client wiring) |
| D-043–049 (art direction suite) | perception | #303 (visual grammar doc) |
| D-033, D-052 (entity color) | perception/content | #303 section 3 (covers #304) |
| D-066 (dual-scale grid) | architecture | #93, #94, #99 (tier system spatial indexing) |

---

## Cross-Team Dependencies

| Dependency | From | To | Risk |
|------------|------|----|------|
| #124 (sound events in ObserverSnapshot) | server | client #125 | Medium — client can stub; wire when ready |
| #193 (line previewer CLI) | server | copy #190, #191, #192 | High — content packs cannot be finalized without tool |
| #303 (visual grammar) | visual | copy #190, #191, #192 via #311, #312, #313 | High — spatial layouts blocked until doc delivered |
| #311, #312, #313 (spatial layouts) | visual | copy #190, #191, #192 | Medium — wireframes unblock draft content |
| #527 (rng_seed in snapshot) | ci | server bridge/types.rs | Low — additive field, no conflict if added carefully |

**Coordination protocol:**
- Server team: signal when #124 (sound events) and #193 (line previewer) are merged to `server` branch. Copy and client teams are waiting.
- Visual team: deliver wireframe versions of #311, #312, #313 immediately after #303 is done (even if full tile maps come later) so copy team can start content packs.
- CI team on #527: coordinate with server on `bridge/types.rs` — confirm no concurrent edits. Add the field as an additive commit.

---

## Sprint Completion Proof

When Sprint 12 is done, the following is concretely observable:

1. **Simulation tier system:** Spawn the test world, set NPC count to 20. Only NPCs within range of the player have `ActiveSim`; distant NPCs have `BackgroundSim`. Promoting an NPC (by walking toward it) takes <5ms. Demoting takes <5ms. Observable in the debug overlay or log output.

2. **Sound event pipeline end-to-end:** In the gauntlet `dialogue_room`, an NPC conversation emits Voice sound events. Close-range events play 2D positional audio on the client World SFX bus. Medium-range events show a color-coded fog-edge directional indicator. No audio errors in the log.

3. **Knowledge boundary enforcement:** The observer query for an entity tagged `OwnerOnly` does not return that component's data for a non-owner observer. Verifiable via Hoshe's unit tests on #139.

4. **Visual grammar document:** `docs/design/visual-grammar-v01.md` exists with all 7 sections (color palette, entity sizing, entity color system, z-level stack, typography, animation tiers, insert overlay). All three spatial layout documents exist for The Terminal, The Last Shift, and the smuggling corridors.

5. **Line previewer CLI:** Running `cargo run --bin line_preview -- --character smuggler --knows smuggling_operation` against a content YAML returns matching lines and exits 0.

6. **v0.1 copy complete:** All copy tickets in this sprint are `done`. The content packs (#190, #191, #192), opening hooks (#299, #300), and all foundation docs (#189, #302, #321, #309) are committed to the `copy` branch.

7. **CI hardening:** `make ci-server` passes with `clippy::disallowed_types` enforced. `--dump-schedule` flag runs without panic. WRONG button `seed.txt` writes a valid u64, not `"unavailable"`.

---

## Test Plan Alignment (D-030)

Sprint 12 is in the integration phase (Sprints 9–12). Test focus:

- **Server:** Unit tests for tier system (#93, #94, #99) — promote/demote timing, `With<ActiveSim>` query correctness. Unit tests for access control (#139) — negative tests: blocked component not returned. Sound event emission tests (#124).
- **Client:** Audio playback tests for #125 — verify correct bus routing. Visual indicator tests for #126 — verify indicator renders at correct fog edge position.
- **CI:** Clippy lint enforcement (#343) — CI must fail on new HashMap usage in simulation crate. Tracing (#344) — binary runs without panic, log output captured.

---

## Decision Coverage Gaps (from sprint prepare)

The following confirmed decisions still have no implementing tickets. Flag to Team Leader if any block Sprint 12 work:

- D-031 (time system / game clock) — no ticket yet; relevant to tier transitions (#99) and NPC routines
- D-033 (entity color = relationship) — covered by #303 visual grammar section
- D-038 (audio in v0.1 — 8 files) — assets done (Sprint 10); integration via #124/#125 this sprint
- D-067 (recognition chime at cognitive delay onset) — no ticket; could be added if capacity permits
- D-068 (5-bus audio architecture) — implementing via #125 this sprint

---

## Notes for Sprint Start

To activate the sprint once planning is approved:

```bash
db/connectors/sprint start
```

This sets Sprint 12 to `active` and marks all sprint tickets as `in_progress` where appropriate. Teams should then run `db/connectors/sprint start-work --team <team>` for their full context dump.