jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(meta): Sprint 17 planning — briefings, workshop brief, close Q-025

Browse Source 
- Write sprint 17 briefings for server, client, copy, visual, joint
- Add Knowledge Flow & NPC Boundaries workshop brief
- Close Q-025 (KG cap/eviction not needed at current scale)
- Assign 9 tickets to Sprint 17: Tell

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-23 23:25:08 +01:00
co-authored by Claude Opus 4.6
parent 41e3b4a9b3
commit abff69a632
7 changed files with 574 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sprints/sprint-17/client.md
+60
View File
@@ -0,0 +1,60 @@
# Sprint 17: Tell — Client Tasks
**Goal:** NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.
**Branch:** `client`
**Agents:** Stig (UI), Tyre (arch), Hoshe (QA)
## Carry-over from Sprint 16
None. Sprint 16 client tickets (#540, #543) will close before Sprint 17.
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #263 | Time display on insert HUD | — |
| #537 | UX: E-Talk overlay improvement | — |
Use `db/connectors/ticket show <id>` for full details.
## Key Decisions
- `decisions/perception.md` — D-019 (camera angle), D-033 (entity color)
- `decisions/architecture.md` — D-020 (Godot client + Rust server via IPC)
- `decisions/scope.md` — D-051 (diegetic insert/minimap)
## Notes
### #263 — Time display on insert HUD
**What exists:** The client has `client/scripts/ui/debug_overlay.gd` for debug display. The insert HUD concept is defined in D-051 but no insert UI code exists yet. `client/scripts/rendering/world_renderer.gd` handles the main rendering pipeline. The server sends `SimulationTime` data in `ObserverSnapshot` (see `server/src/bridge/types.rs`).
**What to deliver:** A diegetic time display on the player's insert/HUD. The player needs to know the current game time for routine-based investigation (NPC schedules, shift changes). Should show time in the station's local format, not abstract tick counts.
**Design dependency:** #314 (visual, this sprint) produces the insert/HUD wireframe. Coordinate with Araminta's output for placement and visual style. Can start with a placeholder layout and refine after the wireframe lands.
**Integration:** Reads `SimulationTime` from the snapshot. No new server work required — time data is already in the protocol.
### #537 — UX: E-Talk overlay improvement
**What exists:** The E-Talk interaction overlay appears when adjacent to an NPC. Playtester feedback says it doesn't communicate enough value — the overlay appears but doesn't convey what talking will accomplish or what access tier is available.
**What to deliver:** Improve the overlay to show: NPC name (if known from KG), relationship state color (from `RelationshipState` in snapshot), and a hint of available dialogue tier (surface/real/secret based on trust level). The goal is to make the player feel informed before committing to a conversation.
**Integration:** All data needed is already in `ObserverSnapshot` — the `VisibleEntity` includes `relationship` state and `known_attributes`. No server changes needed.
## Dependency Chain
```
#263 (Time display) → standalone
#537 (E-Talk UX) → standalone
Both can run in parallel.
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI:
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(client): sprint 17 description" --description "body" --base main --head client
```
docs/sprints/sprint-17/copy.md
+66
View File
@@ -0,0 +1,66 @@
# Sprint 17: Tell — Copy Tasks
**Goal:** NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.
**Branch:** `copy`
**Agents:** Mellanie (author), Paula (narrative), Gestalt (systems)
## Carry-over from Sprint 16
None. Sprint 16 copy ticket (#542, line ID migration) will close before Sprint 17.
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #330 | Diegetic tutorial monologue lines — per character | — (blockers #299, #300 done) |
Use `db/connectors/ticket show <id>` for full details.
## Key Decisions
- `decisions/content.md` — D-035 (tag taxonomy, monologue prerequisites), D-028 (dialogue architecture)
- `decisions/perception.md` — D-019 (camera and perception), D-011 (fog of perception)
## Notes
### #330 — Diegetic tutorial monologue lines — per character
**What exists:** Monologue pools at `content/campaigns/main/systems/krenn/stations/sova/districts/transit/monologue/detective/` and `.../smuggler/` contain character-specific internal monologue. Opening monologue files exist (`opening.yaml` for both characters). The monologue system in `server/src/simulation/monologue.rs` fires lines based on triggers and prerequisites.
**What to deliver:** 8-10 monologue lines per character (smuggler + detective) that teach core mechanics diegetically:
- Movement and exploration ("These corridors all look the same. Mental note: check the signage.")
- Fog of perception ("Can't see past that corner. Might be worth checking.")
- Sound model ("Voices down the hall. Can't make out the words from here.")
- NPC interaction ("Could ask around. People talk if you give them reason to.")
- Insert/HUD usage ("Check the overlay. Should show the time and nearby contacts.")
Lines fire on first-time events (first move, first fog encounter, first sound heard, first NPC proximity, first insert open). Use `trigger: first_time_event` with appropriate event tags.
**Voice consistency:** Smuggler lines should be observational, street-smart, practical. Detective lines should be analytical, procedure-oriented, careful. Both stay in-character — tutorials are disguised as natural inner thoughts, not fourth-wall-breaking instructions.
**Prerequisite format:** Per D-035:
```yaml
- id: pc-smuggler_m_s_tut_001
text: "Voices. Down the corridor. Can't tell how many."
trigger: first_sound_heard
priority: tutorial
cooldown: -1
```
Use `_tut_` in IDs to distinguish tutorial lines from narrative monologue.
**Note on PC monologue ID collision (Q-028):** The review of PR #59 flagged that PC monologue IDs collide across location files. Use the `_tut_` discriminator for tutorial lines. Q-028 will resolve the broader scheme.
## Dependency Chain
```
#330 (Tutorial monologue) → standalone, no deps
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI:
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(content): sprint 17 description" --description "body" --base main --head copy
```
docs/sprints/sprint-17/joint.md
+80
View File
@@ -0,0 +1,80 @@
# Sprint 17: Tell — Joint Tasks
**Goal:** NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.
## Pre-Sprint: Knowledge Flow & NPC Boundaries Workshop
**Brief:** `docs/workshops/knowledge-flow-npc-boundaries/workshop-brief.md`
**Participants:** Tyre (arch), Gestalt (mechanics), Dudley (impl), Paula (narrative), Qatux (docs)
**Timing:** After Sprint 16 closes, before Sprint 17 starts
### Topics and Sprint Impact
| Topic | Resolves | Feeds tickets |
|-------|----------|---------------|
| 1. Knowledge grant mechanism | #141 remaining gap | #172, #149 |
| 2. NPC-NPC knowledge propagation | Q-024 | #172 |
| 3. Unprompted disclosure design | — | #172, #173 |
| 4. NPC information boundaries | #142 | #172 |
| 5. Contradiction detection pipeline | Q-026 | Future (THE FRIEND arc) |
### Expected Outputs
- **D-record** resolving Q-024 and Q-026
- Implementation scope for #141 (wire `knowledge_grant`) and #142 (NPC boundary retrofit priority)
- Mechanical spec for #172 unprompted disclosure
- Updated ticket descriptions for #172 and #173
**#172 is blocked until workshop completes.** Other server tickets can start in parallel.
## Pre-Sprint Decisions
| Decision | Who | Blocks |
|----------|-----|--------|
| Workshop Topics 1-5 | Tyre, Gestalt, Dudley, Paula | #172, #173 |
| Q-028: Collision-resistant line IDs | Gestalt, Tyre | Copy authoring conventions |
## Cross-Team Integration Points
| Server ticket | Client ticket | Integration |
|---------------|---------------|-------------|
| #148 POI data model | #263 Time display | POI data feeds future minimap; time data already in snapshot |
| #232 Protocol versioning | All client | Client must handle version field in messages |
| #172 Unprompted disclosure | #537 E-Talk UX | Disclosure lines appear in dialogue UI; E-Talk overlay should hint at NPC willingness |
| Server ticket | Visual ticket | Integration |
|---------------|---------------|-------------|
| #148 POI data model | #314 Insert/HUD wireframe | POI categories must match wireframe's display elements |
## Sprint Completion Proof
Sprint 17 is **DONE** when:
1. **Unprompted disclosure fires** — An NPC with high trust and relevant knowledge volunteers information to the player without being asked. The volunteered line appears in the dialogue UI. The player's KnowledgeGraph gains a new fact via `knowledge_grant`.
2. **Trait modifiers reshape delivery** — Two NPCs with different personality traits deliver the same base information differently (different mood, different wording or selection weight).
3. **Time is visible** — The insert HUD shows current game time in a diegetic format. Time advances visibly as ticks pass.
4. **POIs exist on the map** — Server spawns POI entities with the `PointOfInterest` component. POIs can be discovered via walking into a location (physical discovery).
5. **Protocol version field exists** — All messages include a version field. Client logs a warning on version mismatch.
6. **E-Talk overlay is informative** — The interaction overlay shows NPC name (if known), relationship color, and a dialogue tier hint.
7. **Insert wireframe is specified** — Both smuggler and detective variants are wireframed with layout, colors, and interaction states documented.
8. **Tutorial monologue fires** — First-time events (move, fog, sound, NPC proximity) trigger diegetic tutorial lines for both characters.
## Test Plan (D-030 alignment)
Sprint 17 is in the **integration testing** phase (Sprints 3-4 per D-030):
- **#172 + #173:** Integration test — NPC with specific axis values and KG state triggers unprompted disclosure; trait modifier changes the selected line.
- **#148 + #149:** Unit tests for POI component CRUD; integration test for discovery event → KG update.
- **#232:** Unit test for version serialization roundtrip; integration test for version mismatch handling.
- **#263:** Manual verification — time display updates as simulation advances.
- **#537:** Manual verification — overlay shows correct NPC data.
- **#330:** Line preview test — tutorial lines fire on first-time triggers, respect cooldown -1 (fire once).
## Teams
| Team | Branch | Agents | Tickets |
|------|--------|--------|---------|
| server | `server` | Dudley, Tyre, Hoshe | #172, #173, #232, #148, #149 |
| client | `client` | Stig, Tyre, Hoshe | #263, #537 |
| copy | `copy` | Mellanie, Paula, Gestalt | #330 |
| visual | `visual` | Araminta | #314 |
docs/sprints/sprint-17/server.md
+103
View File
@@ -0,0 +1,103 @@
# Sprint 17: Tell — Server Tasks
**Goal:** NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.
**Branch:** `server`
**Agents:** Dudley (simulation), Tyre (arch), Hoshe (QA)
## Carry-over from Sprint 16
None. Sprint 16 server was 100% complete (4/4 done).
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #172 | Layer 4: Unprompted disclosure | — |
| #173 | Trait modifier system | — |
| #232 | Create protocol versioning scheme | — |
| #148 | POI data model | — |
| #149 | POI discovery system | #148 |
Use `db/connectors/ticket show <id>` for full details.
## Pre-Sprint Workshop
The **Knowledge Flow & NPC Boundaries** workshop runs before this sprint starts. Brief at `docs/workshops/knowledge-flow-npc-boundaries/workshop-brief.md`. Topics 1-3 directly inform #172 and #173:
- **Topic 1:** Knowledge grant mechanism — how dialogue grants facts to player KG
- **Topic 2:** NPC-to-NPC knowledge propagation (resolves Q-024)
- **Topic 3:** Unprompted disclosure design — how `tell_state.rs` connects to NPC KG
Wait for workshop decisions before starting #172. #148, #149, #232, and #173 can start in parallel.
## Key Decisions
- `decisions/content.md` — D-028 (dialogue architecture, four relational layers), D-024 (NPC 10 axes), D-035 (tag taxonomy)
- `decisions/architecture.md` — D-041 (knowledge graph data model), D-010 (information boundaries), D-020 (engine architecture)
- `decisions/perception.md` — D-033 (entity color from relationship)
## Open Questions to Resolve Early
- **Q-024: Gossip propagation timing** — Resolved by workshop. Feeds #172 implementation.
- **Q-026: Contradiction detection** — Resolved by workshop. Not directly Sprint 17, but workshop output constrains #172 design.
## Notes
### #172 — Layer 4: Unprompted disclosure
**What exists:** `server/src/npc/tell_state.rs` derives tell state from NPC axis values (Secret, ToleranceThreshold, Contentment, MoodState, Relationships). The `TellState` component tracks willingness to volunteer info. `server/src/simulation/dialogue.rs` has the D-028 four-layer pipeline (Layer 1: access tier, Layer 2: situation, Layer 3: trust-gated gossip). Layer 4 is unimplemented.
**What to deliver:** A system that checks NPC `TellState` + `KnowledgeGraph` to select information the NPC wants to volunteer. This is NOT player-initiated — the NPC decides to speak based on mood, trust, and what they know. Workshop Topic 3 will define the trigger conditions and candidate selection algorithm.
**Key gap from audit:** `tell_state.rs` does NOT query the NPC's own `KnowledgeGraph`. NPCs currently operate on ground truth. Workshop Topic 4 (NPC boundaries) will determine the minimum retrofit scope. At minimum, #172 needs `tell_state.rs` to read `&KnowledgeGraph` to know what the NPC can share.
**Integration:** Uses `knowledge_grant` on dialogue lines to give player new facts. Workshop Topic 1 defines the grant schema.
### #173 — Trait modifier system
**What exists:** `server/src/npc/mod.rs` defines NPC components including personality axes per D-024. `server/src/content/line_pool.rs` has the `IndexedDialogueLine` struct with mood and tag fields. No trait-based line transformation exists.
**What to deliver:** A system where NPC personality traits reshape HOW lines are delivered, not per-trait scripts. Base lines exist in the pool; traits modify selection weight, delivery mood, or text variants. Workshop Topic 3 will clarify whether traits also affect WHAT is disclosed (filtering) or just delivery.
**Gotcha:** This must compose with Layer 3 (trust-gated, shipped Sprint 16) and Layer 4 (#172). Trait modifiers should operate as a scoring pass on the already-filtered candidate set, not as a separate filtering stage.
### #232 — Create protocol versioning scheme
**What exists:** `server/src/bridge/types.rs` defines `ObserverSnapshot` and all message types. `client/scripts/protocol/protocol.gd` deserializes them. No version field exists on any message. MessagePack encoding per D-020.
**What to deliver:** Version field in protocol messages, compatibility checking, migration strategy. This is infrastructure — no gameplay change.
**Standalone:** No dependencies on other sprint tickets or workshop output.
### #148 — POI data model
**What exists:** No POI system exists. The `KnowledgeGraph` has `BTreeMap<FactId, FactKnowledge>` for non-entity facts, but POIs are a new domain combining spatial position + knowledge.
**What to deliver:** `PointOfInterest` component with name, location, category, discovery source, visibility rules. This is an ECS component on map entities (bars, terminals, corridors, etc.). POIs feed into the minimap (#151, future) and insert HUD (#263, client Sprint 17).
**Design question:** Do POIs integrate with the knowledge graph as `FactId` entries (e.g., `poi.the_last_shift`), as entity knowledge via `StableId`, or as a separate system? Workshop Topic 1 touches this — POI discovery as knowledge flow.
### #149 — POI discovery system
**What exists:** Nothing. Depends on #148 POI data model.
**What to deliver:** System for learning POIs via: character background (starting knowledge), NPC tips (dialogue grants), research (terminal interaction), physical discovery (walking into a location). Each discovery source maps to a `KnowledgeSource` variant and confidence level.
**Integration:** This IS knowledge flow — uses the same `KnowledgeEventQueue` pattern. New `KnowledgeEventType` variant for POI discovery. Connects to the grant mechanism (Workshop Topic 1).
## Dependency Chain
```
#148 (POI data model) → #149 (POI discovery)
#172 (Unprompted disclosure) → blocked by workshop output
#173 (Trait modifiers) → standalone, parallel
#232 (Protocol versioning) → standalone, parallel
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI:
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(server): sprint 17 description" --description "body" --base main --head server
```
docs/sprints/sprint-17/visual.md
+61
View File
@@ -0,0 +1,61 @@
# Sprint 17: Tell — Visual Tasks
**Goal:** NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.
**Branch:** `visual`
**Agents:** Araminta (art direction)
## Carry-over from Sprint 16
None. Sprint 16 visual ticket (#540, sprite camera angle) will close before Sprint 17.
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #314 | Insert/HUD wireframe and spec — dual character variants | — (blocker #303 done) |
Use `db/connectors/ticket show <id>` for full details.
## Key Decisions
- `decisions/perception.md` — D-019 (camera and perception), D-033 (entity color palette)
- `decisions/scope.md` — D-051 (diegetic insert/minimap)
- `decisions/content.md` — D-024 (NPC 10 axes, relationship display)
## Notes
### #314 — Insert/HUD wireframe and spec — dual character variants
**What exists:** D-051 defines the diegetic insert/minimap concept. D-033 defines the entity color palette (Unknown teal, Known green, PersonOfInterest amber, Hostile red). No wireframe or visual spec exists yet for the insert overlay.
**What to deliver:** Wireframe and visual specification for the lattice overlay HUD with dual-character variants:
**Smuggler variant:**
- Social contacts displayed as dots using D-033 relationship colors
- Casual labels ("The Last Shift", "Kael's usual spot")
- Time display (feeds #263 client implementation)
- Informal, street-level aesthetic — the smuggler's network view
**Detective variant:**
- POIs as amber diamonds with formal labels
- Commission-style grid overlay
- Time display with shift indicators
- Analytical, procedural aesthetic — the detective's investigation tool
**Output format:** Wireframe images (PNG) + written spec document describing layout, color usage, typography, and interaction states. Use `/frame0-wireframe` if Frame0 is available, otherwise produce annotated mockups.
**Integration:** This spec directly feeds #263 (client, time display) and future #151 (minimap rendering). The client team needs placement coordinates and visual hierarchy from this spec.
## Dependency Chain
```
#314 (Insert/HUD wireframe) → standalone, informs #263 (client)
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI:
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(visual): sprint 17 description" --description "body" --base main --head visual
```