Merge remote-tracking branch 'origin/planning'

CHANGELOG.md

@@ -7,6 +7,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- Sprint 12 "Build" briefings — 50 tickets across server, client, copy, visual, ci teams; production-layer foundations + all v0.1 copy authoring
 - `.tmp/` gitignored repo directory for agent temp files — avoids Bash permission prompts during PR review comment posting
 - `sed -n` blanket permission in shared settings
 

docs/sprints/sprint-12/ci.md

@@ -0,0 +1,70 @@
+# Sprint 12: Build — CI Tasks
+
+**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.
+
+**Branch:** `ci`
+**Agents:** Justine (build/deploy)
+
+## Carry-over from Sprint 11
+
+None. Sprint 11 was 7/7 done.
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #343 | Ban HashMap in simulation crate via clippy | — |
+| #344 | Set up tracing crate infrastructure | — |
+| #346 | System dependency graph debug command | — |
+| #527 | Add rng_seed field to ObserverSnapshot for deterministic replay | — |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/architecture.md` — D-020 (Godot + Rust IPC, bridge types), D-041 (knowledge graph, observer snapshot contract)
+- `decisions/scope.md` — D-030 (testing architecture — D-phase alignment)
+
+## Notes
+
+**#343 — Ban HashMap in simulation crate via clippy**
+- Critical priority. Deterministic simulation requires deterministic iteration order; `std::collections::HashMap` does not guarantee this.
+- Add `clippy::disallowed_types` to `.clippy.toml` (or `.cargo/config.toml`'s `[target.*.rustflags]` section) scoped to the `simulation` crate only.
+- Approved alternatives: `BTreeMap` (ordered) or `IndexMap` from the `indexmap` crate (insertion-ordered, deterministic).
+- This lint will surface existing violations. Each violation in `server/src/simulation/` needs a follow-up fix — file separate tickets for each if the count is large, or fix inline if small.
+- CI must fail on new violations after this is merged.
+
+**#344 — Set up tracing crate infrastructure**
+- Add `tracing` and `tracing-subscriber` to `server/Cargo.toml`.
+- Initialize in `server/src/main.rs` with a stdout subscriber in dev (pretty format) and JSON in CI.
+- Add structured log points to: tick duration (`tracing::info!(tick_ms = ...)`), per-system timing (wrap heavy systems with `tracing::instrument`), bridge I/O metrics, tier transition events.
+- This is prerequisite instrumentation for tier system debugging (Sprint 12 server work in #99).
+- In CI (`make ci-server`), the JSON log output should be captured but not asserted on — just confirm the binary runs without panic.
+
+**#346 — System dependency graph debug command**
+- Implement a `--dump-schedule` CLI flag (or `make debug-schedule` Makefile target) that prints the bevy_ecs system ordering and component access patterns.
+- Use bevy's `World::resource::<Schedules>()` or the `bevy_app::App::render_schedule_graph()` approach (check bevy 0.14/0.15 API — confirm current version in `server/Cargo.toml`).
+- Output: plain text or DOT format listing systems in execution order with their component read/write access.
+- CI integration: run on each PR, save output as artifact, diff against baseline to catch unintended system reordering.
+- Lives in `server/src/main.rs` (flag) or a dedicated `server/src/debug.rs` module.
+
+**#527 — Add rng_seed field to ObserverSnapshot for deterministic replay**
+- The WRONG button (#507, done Sprint 11) writes `inputs.jsonl` and `seed.txt` for replay, but `seed.txt` currently writes `"unavailable"` because the server does not include `rng_seed` in `ObserverSnapshot`.
+- Fix: add `rng_seed: Option<u64>` to the `ObserverSnapshot` struct in `server/src/bridge/types.rs`.
+- Populate it from the simulation's RNG state on each tick. The RNG system lives in `server/src/simulation/rng.rs`.
+- This is a server-side change committed from the CI branch. Coordinate with server team to avoid conflict on `bridge/types.rs` — or implement as a separate additive commit that merges cleanly.
+- Completes the WRONG button capture loop. After this, replays can fully reproduce observed bugs.
+
+## Dependency Chain
+
+```
+#343, #344, #346, #527 — all standalone, all 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(ci): Sprint 12 — HashMap lint, tracing infra, schedule debug, rng_seed fix" --description "body" --base main --head ci
+```

docs/sprints/sprint-12/client.md

@@ -0,0 +1,76 @@
+# Sprint 12: Build — Client Tasks
+
+**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.
+
+**Branch:** `client`
+**Agents:** Stig (client dev), Tyre (architect), Hoshe (QA)
+
+## Carry-over from Sprint 11
+
+None. Sprint 11 was 7/7 done.
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #125 | Close-range stereo audio | #124 (server) |
+| #126 | Medium-range visual indicators | — |
+| #345 | Fix entity_renderer.gd field name bug | — |
+| #447 | Resolve OQ-29: dialogue max-width pixel value | — |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/architecture.md` — D-020 (IPC bridge), D-066 (dual-scale grid)
+- `decisions/perception.md` — D-018 (three-range sound model), D-067 (recognition chime at cognitive delay onset), D-068 (5-bus audio architecture), D-069 (audio dip profiles), D-071 (ListeningFocus boost for eavesdropping)
+
+## Open Questions to Resolve Early
+
+- **OQ-29** (#447): Dialogue max-width pixel value. Resolve before any dialogue layout work. Fast resolution — pick a value, record the decision.
+
+## Notes
+
+**#125 — Close-range stereo audio**
+- Blocked by #124 (server sound event system). Start once server delivers `sound_events` in `ObserverSnapshot`.
+- The `audio_manager.gd` autoload (`client/scripts/autoloads/audio_manager.gd`) already exists from Sprint 8. This ticket wires it to the snapshot-driven event loop.
+- Close-range events (RangeCategory::Close) map to 2D positional audio using Godot's `AudioStreamPlayer2D`. Screen-space coordinates from the entity's world position.
+- Asset registry: `AudioAssetRegistry` maps event type (`Footstep`, `Voice`, etc.) to audio file. The 8 audio assets from D-038 (done Sprint 10) are available — use them.
+- D-068 specifies the 5-bus architecture (Master, Ambient, World SFX, Player Actions, UI). Sound events go on the **World SFX** bus.
+- D-069 audio dip: during confrontation, World SFX drops 4–6dB. The dip logic is in `audio_manager.gd` — confirm it's wired to the confrontation state flag.
+
+**#126 — Medium-range visual indicators**
+- Fog-edge directional indicators for sound events outside LOS (RangeCategory::Medium).
+- Arrow or icon at the fog boundary, pointing toward sound source direction. Color-coded per D-018 and D-069: neutral `#c8d0e0`, voices `#e8c547`, danger `#d45d5d`.
+- Triggers an internal monologue description (server-side, but client shows the indicator at the fog edge).
+- Implementation: overlay node on top of `fog_renderer` (`client/scripts/rendering/fog_renderer.gd.uid` — confirm file name). Draw using `_draw()` or a dedicated indicator scene.
+- Does not require #124 to be complete — can implement the indicator rendering standalone with mock data, then wire to snapshot.
+- Visual spec for the fog-edge pulse design (#317, visual team) is in sprint but may not arrive before implementation. Use the D-018 color values as the reference.
+
+**#345 — Fix entity_renderer.gd field name bug**
+- Known bug: `entity_renderer.gd` references `entity.id` but the bridge protocol uses `entity.entity_id`.
+- File: `client/scripts/rendering/entity_renderer.gd`.
+- Fix the field name, add a regression test to the client test suite.
+- Quick fix — do this first to unblock clean rendering for the sprint.
+
+**#447 — Resolve OQ-29: dialogue max-width pixel value**
+- Open question: what is the max pixel width for the dialogue box?
+- Resolution approach: measure against the target resolution, pick a value that fits the grid. Document in `client/scripts/constants.gd` as `DIALOGUE_MAX_WIDTH`.
+- Record the resolved value as a decision if it has downstream impact (it does — affects text wrapping in dialogue UI).
+
+## Dependency Chain
+
+```
+#124 (server, sound events) → #125 (close-range stereo audio)
+#126 (medium-range indicators) — standalone, parallel
+#345 (field name bug) — quick fix, do first
+#447 (OQ-29 resolution) — standalone, do early
+```
+
+## 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(client): Sprint 12 — sound pipeline, medium-range indicators, renderer fix" --description "body" --base main --head client
+```

docs/sprints/sprint-12/copy.md

@@ -0,0 +1,211 @@
+# Sprint 12: Build — Copy Tasks
+
+**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.
+
+**Branch:** `copy`
+**Agents:** Mellanie (author), Paula (narrative), Gestalt (systems), Miri (cultural consultant)
+
+## Carry-over from Sprint 11
+
+None. Sprint 11 was 7/7 done.
+
+## New Tickets
+
+### Foundation docs (unblock everything else — do these first)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #368 | Knowledge vocabulary for v0.1 content | — |
+| #189 | Cultural generation guide — Miri | — |
+| #302 | Sova Texture Appendix | — |
+| #321 | Contraband specification — lattice components + supply chain | — |
+| #179 | Character definition schema | — |
+| #180 | Smuggler character build | — |
+| #181 | Detective character build | — |
+| #182 | Divergent starting knowledge | — |
+| #183 | Divergent relationships | — |
+| #322 | Detective institutional chain of command | — |
+| #320 | Sova Station Profile | — |
+| #336 | Span Gate Transit Schedule | — |
+
+### Setting texture docs
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #335 | Meridian Coverage Map for Sova Transit | #320 |
+
+### Design pattern docs (already unblocked)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #332 | Contradiction arc design document — FRIEND pattern | — |
+| #329 | Mirror moment design document | — |
+| #259 | First 5 minutes experience design | — |
+
+### Knowledge and vocabulary (Gestalt)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #309 | Knowledge state vocabulary for v0.1 | #368 |
+
+### Content packs — Mellanie (depend on foundation docs and line previewer #193 from server)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #190 | Workplace content pack | #189, #193 (server), #302, #321, #311 (visual) |
+| #191 | Bar content pack | #189, #193 (server), #302, #321, #312 (visual) |
+| #192 | Smuggling ring content pack | #189, #193 (server), #302, #321, #313 (visual) |
+
+### Opening content (depend on #309)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #260 | Opening hook content per character | #259 |
+| #299 | Opening hook content — smuggler first 5 minutes | #309 |
+| #300 | Opening hook content — detective first 5 minutes | #309 |
+| #307 | Flat NPC memorable trait pass — 3 flat NPCs | — |
+
+### Supporting content (depend on earlier tickets)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #306 | News ticker / Meridian feed content — 20-30 lines | #302 |
+| #262 | Environmental text content | — |
+| #331 | Diegetic insert flavor text — per character | — |
+| #330 | Diegetic tutorial monologue lines — per character | #299, #300 |
+| #194 | Generation pass expansion | — |
+
+### Parent epic (close when all children done)
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #369 | v0.1 Content Scoping Workshop Outputs (epic) | children above |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/content.md` — D-023 (YAML content format), D-024 (three-tier content pipeline), D-025 (dialogue access tier model), D-028 (internal monologue pools per character), D-029 (THE FRIEND production NPC pattern), D-034 (D-029 confirmed), D-035 (knowledge state vocabulary), D-050 (Velen / Krenn system), D-062 (dialogue system architecture), D-063 (confrontation — same box different weight), D-064 (opening experience design)
+- `decisions/perception.md` — D-016 (internal monologue system), D-032 (separate monologue pools per character)
+- `decisions/scope.md` — D-027 (vertical slice), D-036 (Sova Transit District / Krenn as v0.1 setting), D-037 (contraband spec — unlicensed lattice components), D-039 (v0.1 wow moments — all 6)
+- `decisions/architecture.md` — D-041 (knowledge graph — provides vocabulary foundation via Appendix A)
+
+## Open Questions to Resolve Early
+
+- **#368 → #309 dependency:** Gestalt writes vocabulary doc (#368) first. Paula/Mellanie need #309 (knowledge flags) before writing opening hooks #299/#300. Sequence: #368 → #309 → #299/#300.
+- **Content pack dependency on visual spatial layouts:** #190/#191/#192 are blocked by #311/#312/#313 (Araminta's spatial layouts, visual team). These are a cross-team dependency. If visual spatial layouts slip, content packs must still proceed with draft versions and be finalized once layouts are confirmed.
+
+## Notes
+
+**Sequencing for the sprint — recommended wave order:**
+
+Wave 1 (all parallel, no blockers):
+- #368 (Gestalt) — knowledge vocabulary doc
+- #189 (Miri) — cultural generation guide
+- #302 (Miri) — Sova Texture Appendix
+- #321 (Miri) — contraband spec
+- #179/#180/#181 (Paula) — character definition schema and builds
+- #182/#183 (Paula) — divergent knowledge/relationships
+- #322 (Paula) — detective chain of command
+- #320 (Miri) — Sova Station Profile
+- #336 (Miri) — Span Gate Transit Schedule
+- #332 (Paula) — Contradiction arc doc (FRIEND pattern)
+- #329 (Paula) — Mirror moment doc
+- #259 (Paula) — First 5 minutes experience design
+- #307 (Mellanie) — Flat NPC memorable trait pass
+- #262 (Mellanie) — Environmental text content
+- #331 (Mellanie) — Diegetic insert flavor text
+
+Wave 2 (after Wave 1 foundation docs):
+- #335 (Miri) — Meridian Coverage Map (blocked on #320)
+- #309 (Gestalt) — Knowledge state vocabulary (blocked on #368)
+- #260 (Paula) — Opening hook content per character (blocked on #259)
+- #306 (Mellanie) — News ticker / Meridian feed (blocked on #302)
+
+Wave 3 (after Wave 2 + line previewer #193 from server + spatial layouts from visual):
+- #190 (Mellanie) — Workplace content pack
+- #191 (Mellanie) — Bar content pack
+- #192 (Mellanie) — Smuggling ring content pack
+- #299 (Mellanie/Paula) — Opening hook smuggler (blocked on #309)
+- #300 (Mellanie/Paula) — Opening hook detective (blocked on #309)
+
+Wave 4 (final):
+- #330 (Mellanie) — Diegetic tutorial monologue (blocked on #299, #300)
+- #194 (Mellanie) — Generation pass expansion (LLM-assisted, after packs exist)
+
+**#368 — Knowledge vocabulary for v0.1 content**
+- Owner: Gestalt. Source material: D-041 Appendix A (knowledge graph workshop synthesis).
+- Deliver as a YAML or Markdown doc in `docs/design/` (or wherever content docs live).
+- Categories: entity knowledge (identity, location, behavior, relationship, secret, contraband), world knowledge, prerequisite flag naming conventions (`knows:`, `suspects:`, `met:`, `has_seen:`).
+- This is the foundation for #309 (Paula's knowledge flag list) which unblocks #299/#300.
+
+**#189 — Cultural generation guide — Miri**
+- Blocking dependency for all three content packs (#190, #191, #192).
+- Sova Transit District / Krenn System is the FIRST concrete instance — Miri's output IS the v0.1 cultural voice.
+- Covers: naming conventions, economic vocabulary (what do workers call credits, shifts, cargo), social norms, relationship dynamics in a Commission-regulated transit hub.
+- D-036 confirms Sova Transit District as setting. D-050 establishes Velen/Krenn context.
+
+**#302 — Sova Texture Appendix**
+- 1-page appendix to the Sova setting brief. Fast to write, high leverage — unlocks #190, #191, #192, #306.
+- (1) Slang glossary 15–20 terms, (2) informal decoration (graffiti, stickers), (3) smells and sounds, (4) recurring social rituals.
+- Write as companion to #189 in the same pass.
+
+**#321 — Contraband specification**
+- D-037 confirms: primary contraband = unlicensed lattice components (aftermarket neural mods bypassing Commission regulation).
+- Deliverable: spec doc covering types, supply chain, street names, detection methods.
+- Unlocks #190, #191, #192 — Mellanie needs this before writing any criminal-facing dialogue.
+
+**#179/#180/#181 — Character definition schema and builds**
+- #179: formal schema structure (what fields define a character — starting knowledge, relationships, access permissions, skill flags).
+- #180/#181: Smuggler and Detective as the two concrete instances.
+- These are design documents, not code. Owner: Paula.
+- #182 (divergent starting knowledge) and #183 (divergent relationships) follow from #180/#181.
+
+**#190/#191/#192 — Content packs**
+- The three primary content packs. Each ~165–280 lines.
+- #190 Workplace: cargo workers, supervisors, shift change scripts, manifest disputes.
+- #191 Bar: bartender, regulars, gossip pools, social dialogue (40% more lines than investigation).
+- #192 Smuggling ring: criminals, trust-gated disclosure, coded language, paranoia.
+- All blocked by: #189 (Miri), #193 (line previewer from server team), #302 (texture appendix), #321 (contraband spec), plus respective spatial layouts (#311, #312, #313 from visual team).
+- The line previewer (#193) is a Rust CLI being built by server team this sprint. Coordinate with Dudley/Tyre on delivery timing.
+
+**#299/#300 — Opening hook content**
+- First 10–15 tightly sequenced monologue lines per character.
+- Smuggler: diegetic tutorial for movement, fog, NPC interaction. Establishes criminal motivation.
+- Detective: different emotional register. Arrives into established rhythm. First NPC is adversarial by default.
+- Blocked by #309 (knowledge flags) — lines need to fire on `knows:` prerequisites.
+
+**#307 — Flat NPC memorable trait pass**
+- 3 flat NPCs: Pael (maintenance tech), Ren (drifter), Tev (lookout).
+- Each needs: one memorable observable trait, one "seems important but isn't" line, one visible routine.
+- These are the investigation noise floor — without them the 30/50/20 structure (30% FRIEND, 50% background, 20% flat) collapses.
+
+**#332 — Contradiction arc design document**
+- Reusable pattern from THE FRIEND implementation (#297 Kael, #298 Sera — both done).
+- Document the pattern: 3+ phases with distinct monologue registers, observable contradiction discoverable through observation (not dialogue).
+- Owner: Paula. Already unblocked.
+
+**#329 — Mirror moment design document**
+- 10–15 paired observation triggers. Same event, different character monologue.
+- 7 core mirrors already designed (per ticket): The Friend's Routine, The Empty Corridor, The Overheard Argument, The Familiar Face, The Contraband Scan, The End of Shift, The Missing Person Notice.
+- Owner: Paula. Already unblocked.
+
+## Dependency Chain
+
+```
+#368 (knowledge vocab) → #309 (knowledge flags) → #299, #300 (opening hooks) → #330 (tutorial monologue)
+#189 (Miri guide) + #302 (texture appendix) + #321 (contraband) + #193 (server) + #311/#312/#313 (visual) → #190, #191, #192 (content packs)
+#259 (5 min design) → #260 (opening content per character)
+#320 (station profile) → #335 (Meridian coverage map)
+#179 → #180, #181 → #182, #183
+#332, #329 — standalone (already unblocked)
+#307, #262, #331, #336 — standalone
+```
+
+## 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(copy): Sprint 12 — complete v0.1 content authoring" --description "body" --base main --head copy
+```

docs/sprints/sprint-12/joint.md

@@ -0,0 +1,92 @@
+# 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.

docs/sprints/sprint-12/server.md

@@ -0,0 +1,94 @@
+# Sprint 12: Build — Server Tasks
+
+**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.
+
+**Branch:** `server`
+**Agents:** Dudley (simulation dev), Tyre (architect), Hoshe (QA)
+
+## Carry-over from Sprint 11
+
+None. Sprint 11 was 7/7 done.
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #93 | Tier marker components | — |
+| #94 | Active tier simulation | #93 |
+| #99 | Tier transition logic | #93 |
+| #138 | Information tag schema | — |
+| #139 | Component-level access control | #138 |
+| #124 | Sound event system — server | — |
+| #193 | Line previewer CLI | — |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/architecture.md` — D-020 (Godot + Rust IPC), D-041 (Knowledge Graph data model), D-066 (dual-scale grid: 0.5m sim, 1m visual)
+- `decisions/perception.md` — D-017 (perception modes), D-018 (three-range sound model)
+- `decisions/scope.md` — D-027 (vertical slice), D-053 (movement stance system)
+
+## Notes
+
+**#93 — Tier marker components**
+- Epic #40 (Simulation Tier System) is entirely unstarted — this is the entry point.
+- Deliver three zero-sized marker components: `ActiveSim`, `BackgroundSim`, `StateSaved`.
+- Add a `TierPlugin` that registers them. Tag-based: systems query `With<ActiveSim>` to scope work to nearby NPCs only.
+- Lives in `server/src/simulation/tier.rs` (file exists; currently stubs the stance system — check before overwriting).
+- Integration point: all NPC behavior systems in `server/src/simulation/` should gain `With<ActiveSim>` query filters once this exists.
+
+**#94 — Active tier simulation**
+- Full behavior systems (movement, perception, dialogue, monologue) run at 10–20 ticks/sec for `ActiveSim` NPCs only.
+- Practically: add `With<ActiveSim>` filter to the movement, pathfinding, observation, and monologue systems in `server/src/simulation/`.
+- No new systems needed yet — this is scope-gating existing ones.
+- Blocked by #93 (marker components must exist first).
+
+**#99 — Tier transition logic**
+- Promote `StateSaved → BackgroundSim → ActiveSim` when player approaches; demote on departure.
+- Budget: 2–5ms reactivation. Use `SpatialIndex` trait (see `server/src/simulation/` — check if `SpatialIndex` already exists from earlier sprints; if not, #340 defines it but is still backlog — implement the naive Vec version inline for now).
+- Tier transitions fire on position-change events. Wire to the existing movement system in `server/src/simulation/movement.rs`.
+- Blocked by #93.
+
+**#138 — Information tag schema**
+- Completes the knowledge graph work from Sprints 2–3 (#361–367 all done).
+- Define `ObserverAccess` enum: `Public`, `OwnerOnly`, `FactionOnly(faction_id)`, `RelationshipGated(threshold)`, `KnowledgeGated(flag)`.
+- Add as component metadata attribute — each ECS component that carries sensitive data gets an `#[access = ...]` annotation (or a companion `AccessRule` component).
+- Lives in `server/src/knowledge/types.rs` (already exists — add to the existing types file).
+- This schema is what #139 enforces.
+
+**#139 — Component-level access control**
+- Query filter layer: observer queries (the `observer/` module under `server/src/perception/`) must respect `ObserverAccess` tags before returning data.
+- Implement as a filter function on the observer snapshot builder: `filter_by_access(observer_entity, component_access_rule, kg: &KnowledgeGraph) -> bool`.
+- The `KnowledgeGraph` component (done, `server/src/knowledge/graph.rs`) provides the knowledge state needed for `KnowledgeGated` checks.
+- Blocked by #138.
+
+**#124 — Sound event system — server**
+- `SoundEventEmitter` component: emits typed events (`Footstep`, `Voice`, `Machinery`, `Alert`, `Ambient`) with position, intensity, `RangeCategory` (Close/Medium/Long per D-018).
+- `SoundEventQueue` resource: collects events each tick, fans out to subscribers (client bridge + NPC awareness).
+- Wire into the bridge: sound events within player LOS range → included in `ObserverSnapshot` as a `sound_events` vec.
+- Existing audio manager on client (`client/scripts/autoloads/audio_manager.gd`) expects a `sound_events` array in the snapshot — confirm field name matches.
+- Unblocked (standalone). #125 on client is blocked on this.
+
+**#193 — Line previewer CLI**
+- Rust binary (`tooling/line-previewer` or `server/src/bin/line_preview.rs`) sharing code with the dialogue pipeline.
+- MVP: (1) load YAML content pack, (2) set filter context via CLI flags (`--character smuggler --knows smuggling_operation`), (3) print matching lines, (4) `--explain` mode shows why each line matched/filtered, (5) sequence preview for ordered monologue.
+- Shares `server/src/content/` types (`LinePool`, `ContentLoader`).
+- This tool is what Mellanie needs before authoring content packs — unblocks #190, #191, #192.
+
+## Dependency Chain
+
+```
+#93 (tier markers) → #94 (active sim) → #99 (tier transitions)
+#138 (access schema) → #139 (access control)
+#124 (sound events) — standalone, unblocks client #125
+#193 (line previewer) — standalone, unblocks copy #190, #191, #192
+```
+
+## 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): Sprint 12 server — tier system, sound events, KG access control" --description "body" --base main --head server
+```

docs/sprints/sprint-12/visual.md

@@ -0,0 +1,90 @@
+# Sprint 12: Build — Visual Tasks
+
+**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.
+
+**Branch:** `visual`
+**Agents:** Araminta (art direction)
+
+## Carry-over from Sprint 11
+
+None. Sprint 11 was 7/7 done.
+
+## New Tickets
+
+| # | Title | Blocked by |
+|---|-------|------------|
+| #303 | v0.1 Visual Grammar Document | — |
+| #252 | Placeholder art specification | — |
+| #311 | Spatial layout: Logistics Hub (The Terminal) | #303 |
+| #312 | Spatial layout: Bar (The Last Shift) | #303 |
+| #313 | Spatial layout: Smuggling spaces and transition corridors | #303 |
+
+Use `db/connectors/ticket show <id>` for full details.
+
+## Key Decisions
+
+- `decisions/perception.md` — D-043 (art direction — "functional warmth"), D-044 (visual hierarchy: entity > object > structure), D-045 (environmental neutrality — strict zero shift), D-046 (lighting — three-reference model), D-047 (two-tier animation system), D-048 (neural insert overlay visual design), D-049 (z-level rendering stack — 8 layers)
+- `decisions/scope.md` — D-036 (Sova Transit District as v0.1 setting)
+- `decisions/architecture.md` — D-066 (dual-scale grid: 0.5m simulation, 1m visual)
+- `decisions/content.md` — D-052 (character favorite colors — object-layer identification)
+
+## Notes
+
+**#303 — v0.1 Visual Grammar Document**
+- This is the sprint's single highest-leverage deliverable. It directly unblocks 11 downstream tickets: #304, #311, #312, #313, #314, #315, #316, #317, #318, #333, #334.
+- One document, approximately 4–6 pages. Contents:
+  1. **Color palette** — three zone palettes (logistics hub: cool industrial, bar: warm amber, corridors: neutral) with explicit hex values. Cross-reference D-043 "functional warmth" and D-045 environmental neutrality (environment NEVER shifts to signal danger/safety — only entities carry emotional color).
+  2. **Entity sizing and proportions** — NPC rectangle dimensions at 1m visual grid. Player indicator. Static object sizing.
+  3. **Entity color system** — relationship states (D-033, D-052): unknown=teal `#4a9ebb`, known/friendly=green `#6bc9a6`, person-of-interest=amber `#e8c547`, hostile=red `#d45d5d`, static objects=grey `#8899aa`. This IS #304 content — write it as a section of #303, then close #304 as covered.
+  4. **Z-level layer assignments** — per D-049: 8 layers from floor (0) to UI overlay (7). Which layer gets tiles, NPCs, player, fog, UI elements.
+  5. **Typography baseline** — font (Michroma, introduced Sprint 10), sizes, weights for dialogue, monologue, environmental text, HUD.
+  6. **Animation tier baseline** — per D-047: Tier 1 (8-frame idle/walk loop for Active NPCs) vs Tier 2 (static sprite for Background NPCs).
+  7. **Neural insert overlay** — per D-048: the insert HUD aesthetic. Smuggler vs detective visual variants.
+- Deliver as `docs/design/visual-grammar-v01.md` (or equivalent path in the visual branch).
+- **Write this first.** Everything else in this sprint is blocked on it.
+
+**#252 — Placeholder art specification**
+- Define: tile size in pixels (at 1m visual grid per D-066), NPC sprite dimensions, animation frame count requirements, color palette constraints, file format.
+- This is a short spec document (1–2 pages). Unblocks #133 (placeholder art pipeline implementation).
+- Can be written in parallel with #303 — it feeds from the same decisions (D-043, D-044, D-066) but doesn't need #303 to be complete first.
+
+**#311 — Spatial layout: Logistics Hub (The Terminal)**
+- Tile-level floor plan for the logistics hub. Blocked by #303 (need the visual grammar before doing tile-level design).
+- Contents: scanner bays, main corridor (chokepoint — key player observation position), manifest processing area, break room, supervisor office (window overlooking floor), restricted storage entrance.
+- Include sightline analysis: which positions have LOS to which areas. This feeds #190 (Mellanie's workplace content pack) and is critical for investigation design.
+- D-066 dual-scale grid: draw at 1m visual grid, note that simulation runs at 0.5m internally.
+- Deliver as a diagram or annotated tilemap sketch in `docs/design/` with accompanying notes.
+
+**#312 — Spatial layout: Bar (The Last Shift)**
+- Converted maintenance staging area. Irregular layout is intentional — organic feel per D-043 "functional warmth."
+- Key elements: long bar counter (high visibility from most positions), corner booth (key observation position — can see both entrance and bar), bathroom corridor (secondary exit, NPC private conversations), back room (staff only).
+- Same sightline analysis as #311. Feeds #191 (bar content pack).
+
+**#313 — Spatial layout: Smuggling spaces and transition corridors**
+- The smuggling ring does NOT have a separate building. Operations run through:
+  1. Restricted storage within the logistics hub
+  2. Maintenance corridors (off main paths)
+  3. Dead-drop locations (3 specific spots)
+  4. Transition corridors between hub and bar district (~40m)
+- Mark the corridors with expected NPC traffic density (sparse/moderate/busy affects how conspicuous player movement is).
+- Feeds #192 (smuggling ring content pack).
+
+**Cross-team note:** #311, #312, #313 are blockers for copy team's content packs (#190, #191, #192). Deliver these as early as possible after #303 is done. If full tile maps can't be finalized before content packs start, provide wireframe versions so Mellanie can proceed with draft content.
+
+## Dependency Chain
+
+```
+#303 (visual grammar) → #311, #312, #313 (spatial layouts)
+#252 (placeholder spec) — parallel, standalone
+#311 → unblocks copy #190
+#312 → unblocks copy #191
+#313 → unblocks copy #192
+```
+
+## 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): Sprint 12 — visual grammar, placeholder spec, spatial layouts" --description "body" --base main --head visual
+```