Merge remote-tracking branch 'origin/planning'

# Conflicts:
#	CHANGELOG.md

CHANGELOG.md

@@ -32,6 +32,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - Bar content pack — The Last Shift: 3 NPC dialogue files (#191)
 - Smuggling ring content pack — maintenance corridors: coded vocabulary, dual registers (#192)
 - Generation pass expansion — 80 ambient variant lines across all 9 dialogue files (#194)
+- Sprint 13 "Sound" briefings — 9 tickets across server, client, audio, visual teams; full audio architecture + gauntlet expansion + monologue display spec
 
 ### Fixed
 - Routine tests missing ActiveSim — 3 of 5 tests passed trivially without the required tier marker

docs/sprints/sprint-13/audio.md

@@ -0,0 +1,43 @@
+# Sprint 13: Sound — Audio Tasks
+
+**Goal:** Wire the full audio architecture end-to-end — AudioManager, zone crossfades, dip profiles, recognition chime, and conversation murmur — and complete v0.1 content authoring so opening hooks, tutorial monologue, and all content packs are done.
+
+**Branch:** `audio`
+**Agents:** Inigo (sound design)
+
+## Carry-over from Sprint 12
+
+None. Sprint 12 audio tickets done (#440 interaction audio assets, #453 Sprint 7 asset revision).
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #532 | NPC conversation murmur asset — event-driven World SFX bus wiring | — |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/perception.md` — D-072 (universal event-driven conversation murmur), D-071 (ListeningFocus boost — eavesdrop conspicuousness), D-038 (audio in v0.1 scope — 8 files via Stable Audio Open)
+- `decisions/content.md` — D-074 (audio aesthetic identity — insert-tech vs organic)
+
+## Notes
+
+- **#532 — NPC conversation murmur asset:** Produce a single universal NPC proximity murmur asset via Stable Audio Open per D-072. This is NOT a zone-specific asset — zone ambient determines conspicuousness naturally (bar's dense ambient buries it, corridor's sparse ambient exposes it). The asset should feel like: human voices in an adjacent room — direction and cadence distinguishable, words not. Duration target: 4-8s loopable or a set of short one-shot clips (2-3s each). Route: World SFX bus. Aesthetic per D-074: the audio identity pairs "insert-tech" (synthetic, lattice-flavored for UI/insert sounds) with "organic" (human, environmental for world sounds). The murmur is an organic world sound — warm, human, lived-in. No lattice processing on this one. Deliver to `audio/` directory as `sfx_npc_murmur.ogg` (or similar descriptive name matching the directory-scan pattern the client expects). Signal to client team when asset is committed so they can unblock #533.
+
+## Dependency Chain
+
+```
+#532 (murmur asset) → unblocks client #533 (murmur wiring)
+```
+
+Standalone. Can start immediately.
+
+## PR Workflow
+
+When ready to submit, create a PR with `tea` CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
+
+```bash
+tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(audio): NPC conversation murmur asset" --description "body" --base main --head audio
+```

docs/sprints/sprint-13/client.md

@@ -0,0 +1,60 @@
+# Sprint 13: Sound — Client Tasks
+
+**Goal:** Wire the full audio architecture end-to-end — AudioManager, zone crossfades, dip profiles, recognition chime, and conversation murmur — and complete v0.1 content authoring so opening hooks, tutorial monologue, and all content packs are done.
+
+**Branch:** `client`
+**Agents:** Stig (client dev), Tyre (architect), Hoshe (QA)
+
+## Carry-over from Sprint 12
+
+None. All Sprint 12 client tickets done.
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #528 | AudioManager full implementation — 5-bus setup, directory registry, volume sliders | — |
+| #529 | Zone crossfade implementation — 1.5-2s tween on zone_id change | #528 |
+| #530 | Audio dip profiles — dialogue, confrontation, ListeningFocus boost | #528 |
+| #531 | Recognition chime — fires at cognitive delay onset (D-067) | #528 |
+| #533 | Wire NPC conversation murmur to World SFX bus — event-driven playback | #528, #532 (audio) |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/architecture.md` — D-068 (5-bus audio architecture), D-073 (zone crossfade approach)
+- `decisions/perception.md` — D-067 (recognition chime timing), D-069 (audio dip profiles), D-070 (confrontation as cognitive vulnerability), D-071 (ListeningFocus boost), D-072 (NPC conversation murmur)
+
+## Notes
+
+- **#528 — AudioManager full implementation:** `client/scripts/autoloads/audio_manager.gd` already exists and is substantially built. The 5-bus setup, directory-scan registry, `play()`, `play_at()`, `apply_dip()`, `clear_dip()`, and `set_volume()` methods are all implemented. What remains: (1) `set_zone()` is a stub (`pass`) — this becomes the zone crossfade implementation for #529; (2) volume slider persistence (save/load player preferences); (3) settings UI bindings for the 5 sliders; (4) ensure the Godot project's AudioServer bus layout matches the 5 bus names in code. Before starting, verify bus names in `Project > Audio` match `BUS_MUSIC`, `BUS_AMBIENT`, `BUS_WORLD_SFX`, `BUS_PLAYER_ACTIONS`, `BUS_UI_SOUNDS`.
+
+- **#529 — Zone crossfade:** Implement `set_zone(zone_id: String)` in `audio_manager.gd`. `SimBridge` already receives tile data from `ObserverSnapshot` — determine the player's current tile zone and call `AudioManager.set_zone()` on zone change. Crossfade logic: kill any active ambient tweens, start a 1.5-2s `create_tween()` that fades out the current `_ambient_players` entry and fades in the new zone asset. Zone-to-asset mapping for v0.1: hub/workplace → `amb_hub_layer`, bar → `amb_bar_layer`, smuggling corridor → `amb_corridor_layer` (names must match filenames in `res://audio/`). Crossfade is interruptible — walking back across a boundary starts the reverse tween.
+
+- **#530 — Audio dip profiles:** `DIP_SPECS` and `apply_dip()` / `clear_dip()` are already implemented in `audio_manager.gd`. What remains: wire call sites. Dialogue open/close → `apply_dip("dialogue")` / `clear_dip()`. Confrontation start/end → `apply_dip("confrontation")` / `clear_dip()`. ListeningFocus: the tick gate (30+ stationary ticks) is the caller's responsibility (per existing comment in `audio_manager.gd`); `sim_bridge.gd` or `game_state.gd` must track `stationary_ticks` from the server's `ListeningFocus` field in the snapshot and call `apply_dip("listening_focus")` / `clear_dip()` accordingly. D-070: no UI indicator — the muffling is felt, not announced.
+
+- **#531 — Recognition chime:** `CHIME_RECOGNITION = "sfx_monologue_chime"` is already defined in `audio_manager.gd`. Wire it: when `fog_entities.gd` or `entity_renderer.gd` begins a recognition sequence (detecting `RecognitionTrigger` in the snapshot), call `AudioManager.play(AudioManager.CHIME_RECOGNITION)` at the ONSET of the cognitive delay — not at completion. The chime routes to the `UISounds` bus automatically (default bus in `play()`). Full sequence per D-067: entity detected → chime plays (300-400ms) → 0.6s cognitive delay begins concurrently → monologue text appears during delay → blob transitions to D-033 color + silhouette → recognition complete. The chime is the "unresolved" signal — it precedes recognition, does not confirm it.
+
+- **#533 — NPC murmur wiring:** Blocked by #532 (audio team produces the asset). Once the murmur asset exists in `res://audio/`, wire event-driven playback: when `SimBridge` receives conversation/voice events from `ObserverSnapshot`, call `AudioManager.play_at(asset_key, world_pos, BUS_WORLD_SFX)` for proximity or `AudioManager.play(asset_key, BUS_WORLD_SFX)` for ambient murmur. Single universal asset — zone ambient provides natural conspicuousness (bar's `amb_bar_layer` buries it, corridor's low ambient exposes it). No zone-specific murmur variants.
+
+## Dependency Chain
+
+```
+#528 (AudioManager — complete set_zone + settings UI + slider persistence)
+  → #529 (zone crossfade — implement set_zone body)
+  → #530 (dip profiles — wire call sites in sim_bridge / game_state)
+  → #531 (recognition chime — wire ONSET trigger in fog_entities / entity_renderer)
+  → #533 (murmur wiring) ← also blocked by #532 (audio team asset)
+```
+
+#528 can start immediately. #529, #530, #531 can proceed in parallel once #528 is done.
+#533 waits for both #528 and #532.
+
+## PR Workflow
+
+When ready to submit, create a PR with `tea` CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
+
+```bash
+tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(audio): description" --description "body" --base main --head client
+```

docs/sprints/sprint-13/joint.md

@@ -0,0 +1,96 @@
+# Sprint 13: Sound — Joint / Integration Notes
+
+**Goal:** Wire the full audio architecture end-to-end — AudioManager, zone crossfades, dip profiles, recognition chime, and conversation murmur — and complete v0.1 content authoring so opening hooks, tutorial monologue, and all content packs are done.
+
+**Sprint 13 ID:** 13
+**Status:** planning (activate with `db/connectors/sprint start`)
+
+---
+
+## Pre-Sprint Decisions
+
+The following decisions are implemented this sprint and must be cross-referenced:
+
+| Decision | Domain | Implementing ticket(s) |
+|----------|--------|----------------------|
+| D-067 (recognition chime at cognitive delay onset) | perception | #531 (client) |
+| D-068 (5-bus audio architecture) | architecture | #528 (client) |
+| D-069 (audio dip profiles) | perception | #530 (client) |
+| D-070 (confrontation as cognitive vulnerability) | perception | #530 (client — no UI indicator) |
+| D-071 (ListeningFocus boost for eavesdropping) | perception | #530 (client — 30-tick gate) |
+| D-072 (universal NPC conversation murmur) | perception | #532 (audio), #533 (client) |
+| D-073 (zone crossfade — hard boundary, soft transition) | architecture | #529 (client) |
+| D-074 (audio aesthetic — insert-tech vs organic) | content | #532 (audio — aesthetic guide) |
+| OQ-09 (zone temperature memory — server or client) | perception | #523 (server — resolve + implement) |
+
+---
+
+## Cross-Team Dependencies
+
+| Dependency | From | To | Risk |
+|------------|------|----|------|
+| #532 (murmur asset committed to audio branch) | audio | client #533 | Medium — client can stub; wire when asset arrives |
+| #523 (OQ-09 resolution — zone_id in snapshot?) | server | client #529 | Low — zone crossfade uses zone_id; if not yet in snapshot, server adds it |
+| #315 (monologue display spec) | visual | future client monologue UI (Sprint 14) | Low — #315 output is a spec doc, does not block Sprint 13 client tickets |
+
+**Coordination protocol:**
+- Audio team (#532): Signal to client team when `sfx_npc_murmur.ogg` (or equivalent) is committed to the `audio` branch so #533 can be unblocked.
+- Server team (#523): If OQ-09 resolution requires adding `zone_id` to `ObserverSnapshot` tile data, coordinate with client team on the field name before implementing — client's zone crossfade (#529) reads this field.
+- Client team (#528 first): All other client tickets depend on AudioManager being complete. Start #528 immediately and signal when done so #529, #530, #531 can proceed in parallel.
+
+---
+
+## Sprint Completion Proof
+
+When Sprint 13 is done, the following is concretely observable:
+
+1. **AudioManager production-ready:** Launch the client. Open Project > Audio in Godot — five buses are present: Music, Ambient, WorldSFX, PlayerActions, UISounds. Navigate to settings — five volume sliders appear, one per bus. Adjust a slider — the in-game volume changes in real time and the setting persists across restart.
+
+2. **Zone crossfades:** In the live game, walk from the hub/workplace area into the bar. Within 1.5-2s of crossing the boundary tile, the ambient audio smoothly transitions from hub ambient to bar ambient. Walk back — it reverses. No audio pops. No crossfade artifacts when crossing rapidly.
+
+3. **Audio dip profiles:** Start a conversation with an NPC. Within 300ms, ambient volume drops 6-8dB (relative to slider setting). End the conversation — ambient restores over 500ms. Initiate a confrontation — ambient drops further with a low-pass filter sweep (muffled feel, D-070). Stand still for 30+ seconds (30+ ticks at 10tps) without conversing — world SFX subtly boosts (eavesdrop bonus, D-071). No UI indicator for any of these states.
+
+4. **Recognition chime:** Move near an entity that is in fog but detectable (heard/sensed). The chime plays at the moment of detection (onset of cognitive delay) — before monologue text appears, before the fog blob resolves to a silhouette. Chime is on UISounds bus. Duration is 300-400ms. Monologue text appears during the delay while the chime is still fading.
+
+5. **NPC murmur:** When two NPCs are in conversation range, a soft murmur sound plays on the WorldSFX bus. In the bar, the murmur blends into ambient and is nearly inaudible. In a corridor, the murmur is clearly audible and draws attention. Single asset — same sound in both zones.
+
+6. **Gauntlet rooms:** Running `make test-server` (or `cargo test` in `server/`) executes `sound_lab_*`, `decay_observatory_*`, and `shift_change_*` tests without failure. Tests are deterministic across runs.
+
+7. **OQ-09 resolved:** `decisions/` contains a new or amended decision recording the zone temperature memory approach. If server-tracked: `ObserverSnapshot` tile data includes a `zone_id` field. If client-only: fog shader applies temperature tint from local visited-zone memory. Either way, deep fog in the bar shows a warm dark tint, hub shows cool dark, corridors neutral dark.
+
+8. **Monologue display spec:** `docs/design/monologue-display-spec.md` exists with all required sections: typography, positioning, stacking rules, priority system, fade animation, character color differentiation (with hex values), and 80-character line length constraint.
+
+---
+
+## Test Plan Alignment (D-030)
+
+Sprint 13 is in the integration phase. Test focus:
+
+- **Client:** AudioManager unit tests — registry scan with mock assets, bus setup, dip apply/clear/interrupt, zone crossfade tween timing. Recognition chime test — verify `CHIME_RECOGNITION` plays at snapshot onset, not at recognition completion. All tests via Hoshe's client QA harness.
+- **Server:** Sound Lab, Decay Observatory, Shift Change gauntlet rooms execute correctly. `decay_observatory_*` tests verify BTreeMap-deterministic confidence degradation. `shift_change_*` tests advance the game clock through a phase boundary and verify NPC routine transition.
+- **CI:** `make ci` must pass across all branches before PR. `make pre-pr` runs content cross-reference validation and fixture staleness check. No new HashMap usage in simulation crate (clippy ban still active per #343).
+
+---
+
+## Decision Coverage Gaps (remaining after Sprint 13)
+
+The following confirmed decisions still have no implementing tickets after Sprint 13 closes. Flag to Team Leader if any block upcoming work:
+
+- D-031 (time system / game clock) — `server/src/simulation/time.rs` exists; gauntlet shift change room (#505) exercises it. No standalone ticket. Monitor.
+- D-032 (separate monologue pools per character) — no ticket yet; relevant to monologue system (future sprint).
+- D-033 (entity color = relationship to player) — covered by visual grammar (#303, done) and monologue display spec (#315 this sprint).
+- D-036 (Sova Transit District setting) — no implementation ticket; world map authoring is future.
+- D-038 (audio assets — 8 files) — assets produced (Sprint 10, #327). Integration via #528 and murmur via #532.
+- D-040 (wiki taxonomy) — no ticket; wiki structure is documentation, not code.
+
+---
+
+## Notes for Sprint Start
+
+To activate the sprint once planning is approved:
+
+```bash
+db/connectors/sprint start
+```
+
+This sets Sprint 13 to `active`. Teams then run `db/connectors/sprint start-work --team <team>` for their full context dump.

docs/sprints/sprint-13/server.md

@@ -0,0 +1,52 @@
+# Sprint 13: Sound — Server Tasks
+
+**Goal:** Wire the full audio architecture end-to-end — AudioManager, zone crossfades, dip profiles, recognition chime, and conversation murmur — and complete v0.1 content authoring so opening hooks, tutorial monologue, and all content packs are done.
+
+**Branch:** `server`
+**Agents:** Dudley (simulation dev), Tyre (architect), Hoshe (QA)
+
+## Carry-over from Sprint 12
+
+None. All Sprint 12 server tickets done.
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #505 | Gauntlet rooms: Sound Lab, Decay Observatory, Shift Change | — |
+| #523 | Resolve OQ-09: zone temperature memory — server-tracked or client-only | — |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/architecture.md` — D-020 (IPC bridge, ObserverSnapshot), D-041 (knowledge graph — decay system), D-068 (5-bus audio architecture — zone_id in snapshot)
+- `decisions/perception.md` — D-018 (three-range sound model), D-059 (fog shader — zone temperature tint for OQ-09), D-060 (cognitive delay for fog recognition)
+- `decisions/scope.md` — D-030 (test priority phases — integration phase)
+
+## Notes
+
+- **#505 — Gauntlet rooms: Sound Lab, Decay Observatory, Shift Change:** Three new rooms added to `server/src/test_world/rooms/`. Existing rooms for reference: `server/src/test_world/rooms/` contains `hub.rs`, `inventory_warehouse.rs`, `occlusion_corridor.rs`, `pause_chamber.rs`, `interaction_gallery.rs`, `fog_theater.rs`, `crowd_plaza.rs`, `dialogue_room.rs`, `eavesdrop_alcove.rs`, `sprint_gauntlet.rs`, `confrontation_stage.rs`. Follow the existing room module pattern — each room exports a `build()` function that populates a `World` with ECS components. Add entries to `server/src/test_world/rooms/mod.rs`. The three rooms:
+  - **Sound Lab:** Tests the three-range sound model (D-018). Place sound-emitting entities at calibrated distances. Verify `RangeCategory::Close` events hit the snapshot at <3m, `Medium` at 3-15m, `Long` at 15-40m. Tests: `sound_lab_close_range_in_snapshot`, `sound_lab_medium_range_indicator_present`, `sound_lab_long_range_insert_only`.
+  - **Decay Observatory:** Tests knowledge graph decay (D-041 — decay runs every 10 ticks per D-031). Place entities in LOS, then move player out of LOS. Advance ticks and observe confidence degradation: `Direct` → `KnowsDetails` → `KnowsOf` → `Suspects`. Tests: `decay_observatory_confidence_degrades_after_los_loss`, `decay_observatory_stale_after_threshold`.
+  - **Shift Change:** Tests NPC routine transitions at day phase boundaries (D-031 — Morning/Afternoon/Evening/Night phases). Advance game clock to a phase boundary and verify NPCs transition routine. Tests: `shift_change_npc_transitions_routine_at_phase_boundary`.
+  - Effort estimate: 3d. Sound Lab is the most complex (requires sound event fixture verification).
+
+- **#523 — Resolve OQ-09: zone temperature memory:** This is an architectural decision. D-059 specifies deep fog (previously explored tiles) carries a ~10% zone temperature tint (bar=warm dark, hub=cool dark, corridor=neutral dark). The question: server-tracked or client-only? Arguments: server-tracked = diegetically accurate (server knows which zone each tile belongs to, sends `zone_id` or `zone_temperature` per tile in `ObserverSnapshot`); client-only = simpler (client remembers last-visited zone per tile and applies tint from local memory). The server already sends `zone_id` per tile if D-073 zone crossfade is implemented (client needs zone info for crossfades). If `zone_id` is already in the snapshot for D-073, zone temperature memory is essentially free — client maps `zone_id` → temperature tint from a local lookup table, using the snapshot's `zone_id` per tile. Recommended resolution: server-tracked via `zone_id` (already needed for D-073), client applies temperature tint from local `zone_id → tint` mapping. Write the decision, update `decisions/perception.md` or create a new D-NNN entry, and implement whichever approach is decided. If `zone_id` is not yet in the tile data of `ObserverSnapshot`, add it.
+
+## Dependency Chain
+
+```
+#505 (Sound Lab, Decay Observatory, Shift Change) — standalone, parallel
+#523 (OQ-09 resolution) — standalone, parallel
+```
+
+Both tickets are independent of each other and can proceed in parallel.
+
+## PR Workflow
+
+When ready to submit, create a PR with `tea` CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
+
+```bash
+tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server
+```

docs/sprints/sprint-13/visual.md

@@ -0,0 +1,50 @@
+# Sprint 13: Sound — Visual Tasks
+
+**Goal:** Wire the full audio architecture end-to-end — AudioManager, zone crossfades, dip profiles, recognition chime, and conversation murmur — and complete v0.1 content authoring so opening hooks, tutorial monologue, and all content packs are done.
+
+**Branch:** `visual`
+**Agents:** Araminta (art direction)
+
+## Carry-over from Sprint 12
+
+None. Sprint 12 visual tickets done (#252 placeholder art spec, #303 visual grammar document, #311/#312/#313 spatial layouts).
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #315 | Monologue display system visual spec | #303 (done) |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/perception.md` — D-016 (internal monologue as core perception/atmosphere system), D-033 (entity color = relationship to player), D-043 (visual style — functional warmth), D-044 (visual hierarchy — entity > object > structure)
+- `decisions/architecture.md` — D-049 (Z-level rendering stack — 8 layers), D-066 (dual-scale grid — 0.5m simulation, 1m visual)
+
+## Notes
+
+- **#315 — Monologue display system visual spec:** Araminta owns this spec. It feeds the client implementation of the monologue display UI and constrains copy authoring (line lengths, number of visible lines). The visual grammar document (#303, done) is the foundation — this spec is the applied chapter for monologue specifically. Deliver as `docs/design/monologue-display-spec.md`. Required content:
+  - **Typography:** Font (Michroma, already in client per #517), size, weight. Monologue text is diegetic — the character's interior voice — so it should feel personal and slightly different from environmental UI text.
+  - **Positioning:** Where monologue lines appear on screen. Z-layer (per D-049 8-layer stack — monologue likely Layer 6 or 7, above fog and entities, below UI chrome). Anchoring rule: fixed screen position or entity-relative?
+  - **Stacking rules:** Max 3 lines visible simultaneously. How do they stack — bottom-up, top-down? Do older lines fade while new ones appear?
+  - **Priority system:** Observation monologue > atmosphere monologue > tutorial monologue. When the queue exceeds 3, which lines get dropped or deferred?
+  - **Fade animation:** Fade-in duration, hold duration, fade-out duration. Should lines fade independently or in sync?
+  - **Character differentiation:** Smuggler vs detective. Per D-043 functional warmth — smuggler warmer tones, detective cooler tones. Specify hex color values for each character's monologue text.
+  - **Line length constraint:** Max ~80 characters per line (hard limit for display). This constraint must be published clearly so copy team can author to it.
+  - **Cross-reference:** D-033 color system (entity relationship colors) must not clash with monologue text colors.
+
+## Dependency Chain
+
+```
+#315 (monologue display spec) — standalone, unblocked
+  → referenced by client team for monologue UI implementation (future sprint)
+```
+
+## PR Workflow
+
+When ready to submit, create a PR with `tea` CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
+
+```bash
+tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(visual): monologue display system spec" --description "body" --base main --head visual
+```