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

docs(docs): update Sprint 17 briefings with workshop results

Browse Source 
Reconcile sprint planning after Knowledge Flow workshop:
- Server briefing: add #545-#551 workshop tickets, correct dependency
  chain, reference D-079–D-083, remove stale "blocked by workshop"
- Joint briefing: mark workshop complete, add completion proofs #9
  (contradiction) and #10 (NPC-to-NPC transfer), update teams table
- Copy briefing: add #552 contradiction monologue ticket with full
  Mellanie authoring spec per D-083 and Paula Round 2 output

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-24 02:12:00 +01:00
co-authored by Claude Opus 4.6
parent f685cb7324
commit 0f1b951691
3 changed files with 183 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sprints/sprint-17/copy.md
+31 -3
View File
@@ -7,20 +7,21 @@
## Carry-over from Sprint 16
None. Sprint 16 copy ticket (#542, line ID migration) will close before Sprint 17.
None. Sprint 16 copy ticket (#542, line ID migration) closed.
## New Tickets
## Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #330 | Diegetic tutorial monologue lines — per character | — (blockers #299, #300 done) |
| #552 | Author contradiction monologue lines — Sera/Kael FRIEND arc | — (can author against D-083 spec) |
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)
- `decisions/perception.md` — D-019 (camera and perception), D-011 (fog of perception), D-083 (contradiction detection pipeline)
## Notes
@@ -52,10 +53,37 @@ 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.
### #552 — Author contradiction monologue lines — Sera/Kael FRIEND arc
**What exists:** The monologue system in `server/src/simulation/monologue.rs` handles anomaly/recognition lines. Sprint double-take monologue already fires on `KnowledgeState::Contradicted`. The server team is implementing the contradiction detection pipeline (#547, #550) that will SET this state.
**What to deliver:** Source-named contradiction monologue lines for both characters. These fire when the player discovers a location contradiction — an NPC told them one thing, but they observe something different.
**Canonical example (THE FRIEND arc, D-034):** Sera tells the detective "Kael was at the dock during second shift." The detective later observes Kael in corridor B-7 at that time. Contradiction detected. Monologue fires:
> "Sera said Kael was at the dock. I just saw him in B-7. One of those isn't true."
**Tone principle:** Cognitive dissonance, not accusation. The PC is processing conflicting information, not making judgments. The monologue should feel like genuine internal processing — uncertainty, recalibration, filing away the inconsistency.
**Authoring spec:** See Paula's Round 2 workshop output at `docs/workshops/knowledge-flow-npc-boundaries/paula-round2.md` for the full Mellanie spec, including:
- Phase 2 (Sera/Kael location contradiction) lines
- Phase 3 (deeper contradictions) lines
- Trigger specifications
- The cognitive-dissonance-not-accusation principle
**Both character variants needed:**
- **Detective:** Analytical, procedure-oriented. Notes the discrepancy formally, mentally files it.
- **Smuggler:** Street-smart, instinctive. Gut reaction to being lied to, reads it as a social signal.
**Integration:** The server team (#550) will wire these lines into the monologue system. The `ContradictionDetected` event payload includes `source_display_name` and `subject_display_name` — lines can reference the source NPC by name.
**Can start immediately** — author against the D-083 spec without waiting for server implementation.
## Dependency Chain
```
#330 (Tutorial monologue) → standalone, no deps
#552 (Contradiction monologue) → standalone (author against spec), feeds #550 (server)
```
## PR Workflow
docs/sprints/sprint-17/joint.md
+42 -24
View File
@@ -2,37 +2,44 @@
**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
## Pre-Sprint: Knowledge Flow & NPC Boundaries Workshop (COMPLETE)
**Brief:** `docs/workshops/knowledge-flow-npc-boundaries/workshop-brief.md`
**Outcomes:** `docs/workshops/knowledge-flow-npc-boundaries/workshop-outcomes.md`
**Participants:** Tyre (arch), Gestalt (mechanics), Dudley (impl), Paula (narrative), Qatux (docs)
**Timing:** After Sprint 16 closes, before Sprint 17 starts
**Status:** Complete. All decisions registered, tickets created.
### Topics and Sprint Impact
### Decisions Produced
| 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) |
| Decision | Topic | Key outcome |
|----------|-------|-------------|
| **D-079** | Knowledge Grant Architecture | Compound `KnowledgeGrant` enum (Fact + Entity), `ContentEntityRegistry`, grants fire at line selection |
| **D-080** | NPC-to-NPC Propagation | Transfer via `transfer_npc_knowledge` system, trust-gated, confidence capped at `KnowsOf` |
| **D-081** | Unprompted Disclosure | `DisclosureCandidates` component, trigger gates, three-layer rate limiting, two-stage trait filter |
| **D-082** | NPC Information Boundaries MVP | tell_state + disclosure only, pathfinding deferred, Active-tier only |
| **D-083** | Contradiction Detection Pipeline | Event-driven at KG write time, `ContradictionClaim` struct, 600-tick window |
### Expected Outputs
### Questions Closed
- **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
| Question | Resolution |
|----------|------------|
| **Q-024** | Gossip timing — conversation system hook confirmed |
| **Q-025** | KG memory — not a constraint at current scale, re-evaluate at 200+ Active NPCs |
| **Q-026** | Contradiction detection — event-driven at KG write time with `ContradictionClaim` |
**#172 is blocked until workshop completes.** Other server tickets can start in parallel.
### Team Lead Decision
Entity grants ship in Sprint 17 (overrides FactId workaround). Compound `KnowledgeGrant` with `Entity` variant + `ContentEntityRegistry` at NPC spawn.
### Workshop Tickets Created
7 implementation tickets (#545-#551) under the Knowledge Graph epic, plus #552 (copy team contradiction content). See server briefing for full dependency chain.
## Pre-Sprint Decisions
| Decision | Who | Blocks |
| Decision | Who | Status |
|----------|-----|--------|
| Workshop Topics 1-5 | Tyre, Gestalt, Dudley, Paula | #172, #173 |
| Q-028: Collision-resistant line IDs | Gestalt, Tyre | Copy authoring conventions |
| Workshop Topics 1-5 | Tyre, Gestalt, Dudley, Paula | **Done** — D-079 through D-083 |
| Q-028: Collision-resistant line IDs | Gestalt, Tyre | Open |
## Cross-Team Integration Points
@@ -40,12 +47,16 @@
|---------------|---------------|-------------|
| #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 |
| #551 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 |
| Server ticket | Copy ticket | Integration |
|---------------|-------------|-------------|
| #550 Contradiction monologue | #552 Author contradiction lines | Copy authors lines per D-083 spec; server wires them into monologue system |
## Sprint Completion Proof
Sprint 17 is **DONE** when:
@@ -58,23 +69,30 @@ Sprint 17 is **DONE** when:
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.
9. **Contradiction detection fires** — Location contradiction between `ToldBy` and `DirectObservation` sources marks both entries `Contradicted`. Source-named monologue line triggers. THE FRIEND arc mechanical sequence validates end-to-end.
10. **NPC-to-NPC knowledge transfers** — NPCs in conversation exchange trust-gated facts. `ToldBy` source is constructed. Confidence capped at `KnowsOf`.
## 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.
- **#545 + #546:** Unit tests for `KnowledgeGrant` enum serde roundtrip, `ContentEntityRegistry` resolution, `KnowledgeGranted` event processing.
- **#547 + #550:** Integration test — `ToldBy` entry + `DirectObservation` at different position within 600-tick window → `Contradicted` state → monologue fires → relationship shift → amber color.
- **#548:** Integration test — NPC conversation transfers facts, confidence capped, `ToldBy` source constructed.
- **#549:** Unit test — tell_state reads KG for relationship data, falls through to axes for self-knowledge.
- **#551 + #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).
- **#552:** Content review — contradiction lines follow cognitive-dissonance-not-accusation tone, name source entity.
## Teams
| Team | Branch | Agents | Tickets |
|------|--------|--------|---------|
| server | `server` | Dudley, Tyre, Hoshe | #172, #173, #232, #148, #149 |
| server | `server` | Dudley, Tyre, Hoshe | #545, #546, #547, #548, #549, #550, #551, #141, #142, #172, #173, #148, #149, #232 |
| client | `client` | Stig, Tyre, Hoshe | #263, #537 |
| copy | `copy` | Mellanie, Paula, Gestalt | #330 |
| copy | `copy` | Mellanie, Paula, Gestalt | #330, #552 |
| visual | `visual` | Araminta | #314 |
docs/sprints/sprint-17/server.md
+110 -78
View File
@@ -1,6 +1,6 @@
# 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.
**Goal:** NPCs volunteer information unprompted and express personality through delivery; the knowledge graph becomes a live system with grants, propagation, contradiction detection, and NPC information boundaries; POI infrastructure lands; protocol versioning ships.
**Branch:** `server`
**Agents:** Dudley (simulation), Tyre (arch), Hoshe (QA)
@@ -9,92 +9,124 @@
None. Sprint 16 server was 100% complete (4/4 done).
## New Tickets
## Workshop Output
| # | 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 |
The **Knowledge Flow & NPC Boundaries** workshop completed before this sprint. Outcomes at `docs/workshops/knowledge-flow-npc-boundaries/workshop-outcomes.md`.
**Decisions registered:** D-079 (Grant Architecture), D-080 (NPC-to-NPC Propagation), D-081 (Unprompted Disclosure), D-082 (NPC Information Boundaries MVP), D-083 (Contradiction Detection Pipeline)
**Questions closed:** Q-024 (gossip timing — conversation system hook), Q-025 (KG memory — not a concern at current scale), Q-026 (contradiction detection — event-driven at KG write time)
**Team lead decision:** Entity grants ship in Sprint 17 (compound `KnowledgeGrant` enum with `Entity` variant, `ContentEntityRegistry` at NPC spawn).
## Tickets
### Knowledge Graph Infrastructure (Workshop Tickets)
| # | Title | Priority | Blocked by | Est. lines |
|---|-------|----------|------------|------------|
| **#545** | KnowledgeGrant schema + ContentEntityRegistry | critical | — | ~120 |
| **#546** | KnowledgeGranted event + handler | high | #545 | ~150 |
| **#547** | ContradictionClaim struct + detection in observe_entity | high | #545 | ~160 + tests |
| **#548** | NPC-to-NPC knowledge transfer system | high | #545, #546 | ~160 |
| **#549** | tell_state.rs KG awareness — MVP boundary (#142) | high | #545 | ~35 |
| **#550** | Contradiction monologue + event chain | high | #545, #546, #547, #548, #552 | ~90 |
| **#551** | DisclosureCandidates + unprompted disclosure | high | #545, #546, #548 | ~220 |
### Stories (Acceptance Gates)
| # | Title | Priority | Blocked by |
|---|-------|----------|------------|
| **#141** | Knowledge-based information gating | high | #546 |
| **#142** | NPC information boundaries | high | #546, #548, #549 |
| **#172** | Layer 4: Unprompted disclosure | high | #551 |
| **#173** | Trait modifier system | high | — |
### Standalone
| # | Title | Priority | Blocked by |
|---|-------|----------|------------|
| **#148** | POI data model | high | — |
| **#149** | POI discovery system | high | #148 |
| **#232** | Create protocol versioning scheme | high | — |
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
#545 (KnowledgeGrant schema) ─ CRITICAL ROOT
├─→ #546 (event + handler)
│ ├─→ #548 (NPC-to-NPC transfer)
│ │ ├─→ #551 (disclosure) → #172 (story gate)
│ │ ├─→ #550 (contradiction monologue) ← also needs #547, #552
│ │ └─→ #142 (story gate)
│ └─→ #141 (story gate)
├─→ #547 (ContradictionClaim) → #550
├─→ #549 (tell_state KG) → #142 (story gate)
│
Parallel tracks (no KG deps):
#148 → #149 (POI)
#173 (trait modifiers)
#232 (protocol versioning)
```
**Critical path:** #545 → #546 → #548 → #551 → #172
**Parallel from day 1:** #547 (with #545), #549 (after #545), #148, #173, #232
## Key Decisions
- `decisions/perception.md` — D-079 (grant architecture), D-080 (NPC-to-NPC propagation), D-081 (unprompted disclosure), D-082 (NPC boundaries MVP), D-083 (contradiction detection)
- `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)
## Implementation Notes
### #545 — KnowledgeGrant schema + ContentEntityRegistry
**D-079.** Compound `KnowledgeGrant` enum with `Fact` and `Entity` variants via `#[serde(untagged)]`. `ContentEntityRegistry` resource (`BTreeMap<String, StableId>`) populated at NPC spawn time. ~0.5 day infrastructure. This is the critical root — everything else depends on it.
### #546 — KnowledgeGranted event + handler
**D-079.** New `KnowledgeEventType::KnowledgeGranted` variant. Fires at line selection time in `server/src/simulation/dialogue.rs`. Wires the `knowledge_grant` field on `IndexedDialogueLine` (`server/src/content/line_pool.rs` line 297) — currently `Option<KnowledgeGrant>`, always `None`.
### #547 — ContradictionClaim struct + detection
**D-083.** Add `contradicted_claim: Option<ContradictionClaim>` to `EntityKnowledge`. Detection fires in `observe_entity()` when: existing entry has `source: ToldBy`, position differs, and `|current_tick - told_tick| < CONTRADICTION_WINDOW_TICKS` (600 ticks). Parallel with #546.
### #548 — NPC-to-NPC knowledge transfer
**D-080.** Separate `transfer_npc_knowledge` system (ECS borrow constraint — can't hold two mutable KGs in same system). Runs after `run_npc_conversations`. Trust-gated: Surface 0-1, Real 1-2, Secret 2-3 facts. Confidence capped at `KnowsOf`. Constructs `ToldBy` source.
### #549 — tell_state.rs KG awareness
**D-082.** MVP information boundary. Add `Option<&KnowledgeGraph>` to tell_state query. NPC relationship reads come from KG (other-entity knowledge), self-knowledge stays on axes (always ground truth). ~35 lines, standalone after #545.
### #550 — Contradiction monologue + event chain
**D-083.** `ContradictionDetected` event → monologue system triggers source-named line → relationship shifts to `PersonOfInterest` → `AnomalyMarker` set → D-033 amber color. Pre-resolve `source_display_name` into event payload. Depends on #552 (copy team authors the lines).
### #551 — DisclosureCandidates + unprompted disclosure
**D-081.** `DisclosureCandidates` component (separate from `DerivedTellState`). Trigger gates: trust >= Surface, mood != Hostile, contentment >= -10, witness inhibition, location privacy. Three rate-limit layers: per-fact history, per-NPC 300-tick cooldown, global 1/10-tick StableId-ordered cap. Trait-based two-stage filter (what + how).
### #172 — Layer 4: Unprompted disclosure (story)
Acceptance gate for #551. Verify: NPC with high trust and relevant knowledge volunteers information unprompted. Player's KG gains a new fact via `knowledge_grant`.
### #173 — Trait modifier system
**D-081 two-stage design.** Stage 1: traits filter WHAT is disclosed (Cautious → KnowsDetails minimum, Gossipy → Suspects minimum). Stage 2: traits modify HOW (delivery mood, line selection weight). Composes with Layer 3 (trust-gated) and Layer 4 (#551).
### #148 / #149 — POI data model + discovery
POIs enter KG as `FactId("poi.*")` namespace per D-079. `PointOfInterest` component with name, location, category, discovery source, visibility rules. Discovery via `KnowledgeEventType::KnowledgeGranted` with `Fact` variant.
### #232 — Protocol versioning
Standalone infrastructure. Version field in protocol messages, compatibility checking, migration strategy. No gameplay change.
## PR Workflow
When ready to submit, create a PR with `tea` CLI: