# 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
```