diff --git a/docs/sprints/sprint-12/ci.md b/docs/sprints/sprint-12/ci.md new file mode 100644 index 000000000..5933fa706 --- /dev/null +++ b/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 ` 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::()` 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` 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 +``` diff --git a/docs/sprints/sprint-12/client.md b/docs/sprints/sprint-12/client.md new file mode 100644 index 000000000..0f507228e --- /dev/null +++ b/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 ` 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 +``` diff --git a/docs/sprints/sprint-12/copy.md b/docs/sprints/sprint-12/copy.md new file mode 100644 index 000000000..09b002a06 --- /dev/null +++ b/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 ` 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 +``` diff --git a/docs/sprints/sprint-12/joint.md b/docs/sprints/sprint-12/joint.md new file mode 100644 index 000000000..626a9a158 --- /dev/null +++ b/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` 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 ` for their full context dump. diff --git a/docs/sprints/sprint-12/server.md b/docs/sprints/sprint-12/server.md new file mode 100644 index 000000000..b9a6389ee --- /dev/null +++ b/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 ` 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` 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` 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` 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 +``` diff --git a/docs/sprints/sprint-12/visual.md b/docs/sprints/sprint-12/visual.md new file mode 100644 index 000000000..4bb79be60 --- /dev/null +++ b/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 ` 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 +```