From ed09439a31ad1a8ec508aa7b96ffa306e2587695 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 12 Feb 2026 02:14:52 +0100 Subject: [PATCH] docs(sprints): add Sprint 3 "Know" team briefings NPC data model, pathfinding, observation events, and interaction foundation. Briefings for server, client, joint, and copy teams. Co-Authored-By: Claude Opus 4.6 --- docs/sprints/sprint-3/client.md | 58 ++++++++++++ docs/sprints/sprint-3/copy.md | 154 ++++++++++++++++++++++++++++++++ docs/sprints/sprint-3/joint.md | 87 ++++++++++++++++++ docs/sprints/sprint-3/server.md | 60 +++++++++++++ 4 files changed, 359 insertions(+) create mode 100644 docs/sprints/sprint-3/client.md create mode 100644 docs/sprints/sprint-3/copy.md create mode 100644 docs/sprints/sprint-3/joint.md create mode 100644 docs/sprints/sprint-3/server.md diff --git a/docs/sprints/sprint-3/client.md b/docs/sprints/sprint-3/client.md new file mode 100644 index 000000000..bd263a140 --- /dev/null +++ b/docs/sprints/sprint-3/client.md @@ -0,0 +1,58 @@ +# Sprint 3: Know — Client Tasks + +**Goal:** Player character can observe NPCs, track their knowledge, and interact with the environment through a working observation event pipeline. + +**Branch:** `client` +**Agents:** Stig (UI), Tyre (architecture), Hoshe (QA) + +## Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #345 | Fix entity_renderer.gd field name bug (id vs entity_id) | — | +| #240 | Player interaction system and dispatcher | — | + +Use `db/connectors/ticket show ` for full details. + +## Key Decisions + +- `decisions/architecture.md` — D-020 (IPC protocol), D-030 (testability) +- `decisions/perception.md` — D-016 (internal monologue), D-017 (perception modes) +- `decisions/content.md` — D-028 (dialogue architecture), D-035 (tag taxonomy) + +## Notes + +**#345 (Critical bug fix):** +- **Context:** Line 26 of `client/scripts/rendering/entity_renderer.gd` checks `entity_data.has("entity_id")` (correct per Protocol v2), but this was identified as a field name bug in the Architecture Review Audit. Verify the check is correct and that entities render properly. If the bug is real, the fix is trivial (XS effort). If entities already render, mark done and document why the audit flagged it incorrectly. +- **File:** `/var/home/jeroenschweitzer/Projects/settled-reach/main/client/scripts/rendering/entity_renderer.gd` +- Start with this — it's blocking basic entity rendering if the bug is real. + +**#240 (Interaction system):** +- **Context:** General-purpose interaction dispatcher that routes player Interact input to appropriate subsystems. Currently there is no interaction system — player can move but not interact with anything. +- **Routing logic:** + - NPC → dialogue (Sprint 4+, stub for now) + - Object → examine (Sprint 4+, stub for now) + - Door → open/close (Sprint 4+, stub for now) + - Terminal → info access (Sprint 4+, stub for now) +- **Implementation:** Add `Interactable` component concept on server side. Client sends `Interact` input when player presses interact key near an entity. Server dispatcher checks entity type and routes to appropriate handler. For Sprint 3: infrastructure only, all handlers return placeholder text. +- **Files:** + - Server: `server/src/simulation/interaction.rs` (new module) + - Client: `client/scripts/autoloads/input_mapper.gd` (add interact key binding) +- **Integration:** Builds on existing input system (`server/src/simulation/input.rs`, `client/scripts/autoloads/input_mapper.gd`). New input type: `PlayerInput::Interact { target_entity: Option }`. +- This is foundation work for dialogue (#168, Sprint 4+) and follow/examine mechanics (#241, #242, Sprint 4+). + +## Dependency Chain + +``` +#345 (bug fix) → standalone, critical for entity rendering +#240 (interaction dispatcher) → #168, #241, #242 (Sprint 4+ dialogue/mechanics) +``` + +Both tickets are independent and can run in parallel if multiple agents are available. + +## 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): description" --description "body" --base main --head client +``` diff --git a/docs/sprints/sprint-3/copy.md b/docs/sprints/sprint-3/copy.md new file mode 100644 index 000000000..1cc2e46d6 --- /dev/null +++ b/docs/sprints/sprint-3/copy.md @@ -0,0 +1,154 @@ +# Sprint 3: Know — Copy Tasks + +**Goal:** Complete the knowledge vocabulary document to unblock content authoring. + +**Branch:** Content work feeds into multiple branches (no code branch) +**Agents:** Mellanie (authoring), Paula (narrative design), Gestalt (systems design) + +## Carry-over from Sprint 2 + +| # | Title | Status | Notes | +|---|-------|--------|-------| +| #368 | Knowledge vocabulary for v0.1 content | in_progress | Started Sprint 2, carries to Sprint 3 | + +## Context + +Sprint 2 started the knowledge vocabulary document (`docs/design/knowledge-vocabulary-v0.1.md`). Sprint 3 completes it. + +The knowledge graph data structures are implemented (Sprint 2, tickets #361-367). The observation event pipeline is being built (Sprint 3, ticket #239). The content team needs to define what *goes into* those containers — the FactIds, EntityKnowledge attribute keys, and RelationshipState transition triggers that actual gameplay content will reference. + +Without this vocabulary: +- Mellanie can't write monologue prerequisites (`prerequisite: { suspects: "manifest_discrepancy" }` — is `manifest_discrepancy` a valid FactId?) +- Paula can't design NPC profiles with knowledge gates (what `known_attributes` keys exist?) +- The observation event generator (#239) can't map NPC behaviors to meaningful triggers (what counts as a "social anomaly"?) + +This ticket unblocks content authoring ticket #309 (Sprint 4+) and is the bridge between knowledge graph implementation and actual content. + +## Assigned Ticket + +| # | Title | Priority | Est. | Blocked by | +|---|-------|----------|------|------------| +| #368 | Knowledge vocabulary for v0.1 content (#309) | high | 0.5d | — | + +Use `db/connectors/ticket show 368` for full details. + +## What You're Delivering + +A design document: `docs/design/knowledge-vocabulary-v0.1.md` + +The document must define: + +### 1. FactId Categories for v0.1 + +`FactId` is the identifier for non-entity knowledge (see `server/src/knowledge/types.rs` lines 21-25). Format: `"category.topic"` (e.g., `"contraband.ring_exists"`). + +Define 15-25 concrete FactIds for v0.1 scope covering: +- **Contraband knowledge** (ring existence, lattice components, medical-grade replacements, Severance tech per D-037) +- **Location knowledge** (restricted corridors, smuggling routes, surveillance coverage, span gate schedules) +- **Event knowledge** (manifest discrepancies, suspicious meetings, evidence discoveries) +- **World knowledge** (Commission regulations, Syndic supply chains, Sova District context per D-036) +- **Relationship knowledge** (trust networks, faction allegiances, personal connections) +- **Investigation progress** (investigation stages, evidence collected, confrontation triggers) + +Each FactId must map to the 4-level confidence hierarchy (Suspects / KnowsOf / KnowsDetails / Direct). Example: + +``` +contraband.ring_exists + - Suspects: "There's off-the-books cargo moving through here" + - KnowsOf: "There's a smuggling ring operating in Sova" + - KnowsDetails: "Kael, Voss, and Drin are running lattice components through customs bypass" + +location.corridor_b7_restricted + - Suspects: "B-7 access is tighter than it should be" + - KnowsOf: "B-7 requires dock credentials after 18:00" + - KnowsDetails: "B-7 is the primary smuggling handoff point, Commission sweeps at shift change" +``` + +### 2. EntityKnowledge Attribute Keys + +`EntityKnowledge.known_attributes` is a `BTreeMap` (see `server/src/knowledge/types.rs` lines 163-165). Define the canonical keys for v0.1: + +- **Identity:** `name`, `role`, `faction`, `species` (human assumed for v0.1) +- **Social:** `relationship_type` (colleague, friend, regular, contact, rival), `trust_level` (low/medium/high) +- **Behavioral:** `routine_pattern` (shift worker, bar regular, transient), `behavior_flags` (avoidant, talkative, nervous, defensive) +- **Secrets:** `secret_held` (freeform description), `secret_confidence` (Suspects/KnowsOf/KnowsDetails) +- **Investigation:** `tell_observed` (description of observable tell), `contradiction_flagged` (yes/no) + +Provide 3-5 example EntityKnowledge entries for v0.1 NPCs (Kael Davan, Sera Venn, Lera Sessik, Torek Lintar, Voss Krenn) showing how these keys populate. Use D-034 FRIEND profiles as reference. + +### 3. RelationshipState Transition Patterns + +`RelationshipState` drives entity color rendering (see D-033, `server/src/knowledge/types.rs` lines 117-140). The enum is: +- `Unknown` (teal) +- `Known` (soft green) +- `Friendly` (soft green, trusted) +- `PersonOfInterest` (amber, flagged by investigation) +- `Hostile` (red, character knows there is danger) + +Define the canonical transition triggers for v0.1: + +**Unknown → Known:** +- First direct observation with name attribution +- Told about entity by trusted source + +**Known → Friendly:** +- Trust-gated dialogue completed (D-028 Layer 3 "real" tier accessed) +- Multiple positive interactions without contradictions +- Entity provides useful information + +**Known/Friendly → PersonOfInterest:** +- Monologue triggers "something's off" (Suspects-level knowledge about this entity's contradiction) +- Observable tell detected (D-034 tell system) +- Entity avoids specific topics or NPCs + +**PersonOfInterest → Hostile:** +- KnowsDetails-level knowledge of entity's threat to player +- Direct observation of hostile action +- Contradiction confirmed (THE FRIEND arc climax, D-034) + +**Known/Friendly → Hostile:** +- Direct observation of hostile action with no warning +- Emergency trust collapse (rare) + +### 4. Observation Event Trigger Definitions + +The observation event generator (#239) needs to know what counts as a "meaningful observation." Define the 5 trigger types with concrete examples: + +1. **Routine deviation:** NPC not at expected location during their scheduled time +2. **Absence detection:** Expected NPC missing from usual location +3. **Social anomaly:** Unexpected NPC pairing or avoidance behavior +4. **New information:** First observation of an entity/location/behavior +5. **Contradiction:** Observed behavior conflicts with told information + +Each trigger type should map to specific NPC axis data (D-024) and monologue tone. + +## Key Decisions + +- `decisions/architecture.md` — D-041 (Knowledge Graph Data Model — canonical structs) +- `decisions/content.md` — D-024 (10-axis NPC model), D-034 (THE FRIEND pattern), D-035 (tag taxonomy), D-036 (Sova setting), D-037 (contraband) +- `decisions/perception.md` — D-016 (internal monologue), D-033 (entity color = relationship) + +## Canonical References + +- Knowledge graph structs: `server/src/knowledge/types.rs` +- Knowledge graph canonical design: `docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md` (Part 3, lines 320-752) +- THE FRIEND profiles: D-034 (Kael Davan, Sera Venn) +- Setting details: D-036 (Sova Transit District, Krenn System) +- Contraband details: D-037 (lattice components) + +## Completion Criteria + +The document is complete when: +1. All 4 sections (FactIds, EntityKnowledge keys, RelationshipState triggers, Observation triggers) are filled with concrete examples +2. Each FactId has confidence-level descriptions +3. EntityKnowledge examples cover at least 3 v0.1 NPCs +4. RelationshipState transitions map to specific gameplay events +5. Observation triggers reference specific NPC axis combinations + +This unblocks #309 (content authoring), which is the first monologue/dialogue writing ticket. + +## Notes + +- **Sprint 2 progress:** If significant work was done in Sprint 2, review and complete remaining sections. If minimal progress, prioritize FactIds and EntityKnowledge keys first (those block #309 most directly). +- **Cross-team coordination:** Observation event trigger definitions should align with server ticket #239 implementation. Gestalt should coordinate with Dudley on trigger semantics. +- **Authoring ergonomics:** The vocabulary should be *author-friendly*. FactIds should read like natural language. Attribute keys should be memorable. Avoid cryptic codes. diff --git a/docs/sprints/sprint-3/joint.md b/docs/sprints/sprint-3/joint.md new file mode 100644 index 000000000..347915f5b --- /dev/null +++ b/docs/sprints/sprint-3/joint.md @@ -0,0 +1,87 @@ +# Sprint 3: Know — Joint Tasks + +**Goal:** Player character can observe NPCs, track their knowledge, and interact with the environment through a working observation event pipeline. + +**Branches:** `server` + `client` (merge to main for integration) + +## Joint Tickets (Split Per Team) + +Joint tickets are split between server and client teams. Work happens on separate branches, merges through main. + +### #341: Basic IPC error handling implementation + +**Split:** +- **Server half:** Deserialization failure handling (log + dump raw bytes), clean shutdown on pipe break + - Assigned to: server team (Dudley) + - Files: `server/src/bridge/local.rs`, `server/src/bridge/tcp.rs` +- **Client half:** Server crash detection (SIGCHLD), error dialog with last log lines, pipe break handling + - Assigned to: client team (Stig) + - Files: `client/scripts/protocol/server_process.gd`, `client/scripts/protocol/local_bridge.gd` + +**Blocker:** None — both sides can implement independently against the D-020 IPC contract. + +### #84: Multiple entity sync + +**Split:** +- **Server half:** Add 2-3 NPCs to simulation with proper TilePosition + Npc components, ensure all appear in ObserverSnapshot + - Assigned to: server team (Dudley) + - Files: `server/src/main.rs` (world spawn setup) + - Depends on: #86 (NPC components), #236 (done) +- **Client half:** Verify all entities render correctly from snapshot data, test entity lifecycle (appear/disappear/move) + - Assigned to: client team (Stig) + - Files: `client/scripts/rendering/entity_renderer.gd` + - Depends on: #345 (bug fix) + +**Integration point:** Both halves can be tested independently (server logs snapshot content, client uses test data), then integrated through the existing IPC bridge. + +Use `db/connectors/ticket show ` for full details. + +## Key Decisions + +- `decisions/architecture.md` — D-020 (subprocess IPC), D-010 (client-server separation), D-030 (testability) +- `decisions/content.md` — D-024 (NPC model), D-027 (vertical slice criteria) + +## Sprint Completion Proof + +**"Walk around and notice NPCs"** — the sprint is done when: + +1. Fog and LOS work (Sprint 2 baseline, maintained) +2. Multiple NPCs appear on screen with distinct colors +3. NPCs have daily routines and pathfinding works +4. Player can attempt to interact (dispatcher exists, even if handlers are stubs) +5. Observation events generate when NPCs do something interesting +6. IPC errors display useful messages instead of silent crashes +7. Entity rendering bug (#345) is verified fixed or documented as non-issue + +**Observation pipeline proof:** Spawn an NPC at a scheduled location. The server generates an observation event when the NPC is in LOS. Logs confirm the event was generated with correct trigger type and NPC reference. + +This is the first moment NPCs feel like *people* instead of sprites — they move with purpose, and the game notices when something is off. + +## Notes + +- **#341 (IPC error handling):** Sprint 1-2 had minimal error handling — crashes were silent or cryptic. This ticket adds the minimum viable error UX: deserialization failures show raw data for debugging, server crashes show log tail in a dialog, pipe breaks shut down cleanly. Improves developer experience and prevents "what just happened" moments. +- **#84 (Multiple entity sync):** Sprint 1-2 had a single player entity. This ticket proves the sync layer works with multiple entities. The server-side work overlaps with #86 (NPC components) — if #86 is done first, this becomes trivial. The client-side work depends on #345 being resolved. +- **Test plan per D-030 Phase 1:** Sprint 3 bridges Phase 1 and Phase 2. Collision/pathfinding tests (#237) continue Phase 1 focus. Observation event generation (#239) is the first Phase 2 work (monologue pipeline integration test). + +## Dependency Chain + +``` +Server branch: +#341 (IPC error, server) → standalone, no blockers +#84 (multi-entity, server) → blocked by #86 (NPC components) + +Client branch: +#341 (IPC error, client) → standalone, no blockers +#84 (multi-entity, client) → blocked by #345 (bug fix) + +Integration: +Both halves of #341 merge independently +Both halves of #84 merge when both are complete +``` + +## 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(scope): description" --description "body" --base main --head +``` diff --git a/docs/sprints/sprint-3/server.md b/docs/sprints/sprint-3/server.md new file mode 100644 index 000000000..8c5417075 --- /dev/null +++ b/docs/sprints/sprint-3/server.md @@ -0,0 +1,60 @@ +# Sprint 3: Know — Server Tasks + +**Goal:** Player character can observe NPCs, track their knowledge, and interact with the environment through a working observation event pipeline. + +**Branch:** `server` +**Agents:** Dudley (simulation), Tyre (architecture), Hoshe (QA) + +## Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #86 | Core NPC components | — | +| #87 | Relationship system | — | +| #88 | Daily routine system | #25 (done) | +| #237 | Tile-based A* pathfinding | #236 (done) | +| #238 | NPC path following and movement | #237 | +| #239 | Observation event generator | — | + +Use `db/connectors/ticket show ` for full details. + +## Key Decisions + +- `decisions/content.md` — D-024 (10-axis NPC model), D-034 (THE FRIEND pattern), D-035 (dialogue tag taxonomy) +- `decisions/architecture.md` — D-041 (Knowledge Graph), D-026 (simulation tiers), D-030 (testability), D-031 (time system) +- `decisions/perception.md` — D-011 (fog/perception), D-016 (internal monologue), D-017 (perception modes) + +## Notes + +**NPC foundation tickets (#86, #87, #88):** +- **#86 (Core NPC components):** The `Npc` marker component and basic axes already exist in `server/src/npc/mod.rs` (Want, Secret, Relationships, ToleranceThreshold, DailyRoutine, InformationInventory, Contentment, plus supporting axes). This ticket extends those component definitions to match the full D-024 10-axis model with proper field types. DailyRoutine needs to become a structured schedule with time-based location transitions. +- **#87 (Relationship system):** The `Relationships` component exists as a stub. Implement the RelationshipGraph resource (per D-024) for NPC-to-NPC connections with trust/history metadata. Keep per-NPC relationship slots (3 key relationships) for Active-tier NPCs. This is separate from the KnowledgeGraph (what entities *know*) — this is what entities *feel*. +- **#88 (Daily routine system):** Build on SimulationTime (done in #25, `server/src/simulation/time.rs`). DailyRoutine component stores location schedule with day-phase transitions (Morning/Afternoon/Evening/Night per D-031). NPCs transition between locations at phase boundaries. Foundation for routine deviation detection (#243, Sprint 4+). + +**Pathfinding tickets (#237, #238):** +- **#237 (Pathfinding):** A* pathfinding over the WalkabilityMap (done in #236, `server/src/simulation/movement.rs`). Use the `pathfinding` crate. NPCs request paths between positions; system returns tile sequences. Output: `PathRequest` event + `ComputedPath` component. This blocks routine execution — NPCs can't move between routine locations without pathfinding. +- **#238 (Path following):** Per-tick NPC position updates along computed paths. Separate from pathfinding computation. Smooth interpolation between tiles (fractional TilePosition or separate VisualPosition component). Movement speed parameter. This is the execution system that makes NPCs actually walk. + +**Observation pipeline (#239):** +- **#239 (Observation event generator):** The mechanical heart of the game per Gestalt. Compares ObserverSnapshot against character KnowledgeGraph to generate ObservationEvents. Trigger types: routine deviation, absence detection, social anomaly, new information, contradiction. Character-specific — same NPC behavior generates different events for smuggler vs detective. Foundation for monologue generation (#119, Sprint 4+). +- Existing foundation: `server/src/perception/observation.rs` already emits DirectObservation and LeftLOS events. This ticket adds the *interpretation* layer — detecting *meaningful* observations like routine deviations, not just visibility changes. +- Integration points: Reads KnowledgeGraph (Sprint 2, done), reads DailyRoutine (this sprint, #88), emits to a new ObservationEventQueue resource. + +## Dependency Chain + +``` +#86 (NPC components) → #239 (needs NPC profiles to compare against) +#87 (relationships) → standalone, feeds NPC generation pipeline (#92, Sprint 4+) +#88 (routines) → #239 (routine deviation requires routine data) +#237 (pathfinding) → #238 (path following) → #101 (routine execution, Sprint 4+) +#239 (observation) → #119 (monologue generation, Sprint 4+) +``` + +#86, #87, #237 can start immediately. #88 and #239 depend on completions but not each other. + +## PR Workflow + +When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section): +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server +```