jpmschweitzerandClaude Opus 4.6
e8263e209e
System S-057 assigned to real star GJ 35 (Van Maanen's Star, DG white dwarf at 13.9 ly). Renamed across all content, server code, docs, decisions, wiki lore, and config files. 224 files updated. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
241 lines
12 KiB
Markdown
241 lines
12 KiB
Markdown
# Sprint 2: See — Copy Tasks
|
|
|
|
**Goal:** Define the knowledge vocabulary that content authoring requires. Deliver the FactId categories, known_attributes keys, and RelationshipState transition patterns for v0.1.
|
|
|
|
**Branch:** Content work feeds into multiple branches (server knowledge graph, client dialogue system, design documents)
|
|
**Agents:** Mellanie (authoring), Paula (narrative design), Gestalt (systems design)
|
|
|
|
## Context
|
|
|
|
Sprint 2 delivers the knowledge graph data structures on the server side (tickets #361-367). The knowledge graph is THE mechanism that gates dialogue, triggers monologue, and drives THE FRIEND contradiction arc. But the server team is implementing empty containers — they need the content team to define what goes in those containers.
|
|
|
|
Your role this sprint: **define the controlled vocabulary for v0.1 content.**
|
|
|
|
When Mellanie writes a monologue line with `prerequisite: { suspects: "manifest_discrepancy" }`, the server needs to know that `manifest_discrepancy` is a valid FactId. When Paula designs Kael Davan's profile with `known_attributes: { role: "dock_worker", faction: "ring_member" }`, the dialogue system needs to know those are the canonical keys. When the contradiction detection system marks an entry as `Contradicted`, the content needs to know what relationship state transitions make sense.
|
|
|
|
This ticket unblocks content authoring (#309) and is the bridge between the knowledge graph implementation and actual gameplay 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 the categories and 15-25 concrete FactIds for v0.1 scope. Categories must cover:
|
|
- **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<String, String>` (see `server/src/knowledge/types.rs` lines 163-165). Define the canonical keys for v0.1. Must include:
|
|
|
|
- **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 Van Maanen's Star) 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:**
|
|
- Skip PersonOfInterest if threat is immediate and unambiguous
|
|
- Cover blown scenario
|
|
- Direct aggression observed
|
|
|
|
Provide 2-3 concrete examples mapping to v0.1 narrative beats (e.g., Kael's arc for smuggler, Sera's arc for detective).
|
|
|
|
### 4. KnowledgeState Usage for v0.1
|
|
|
|
`KnowledgeState` is `Active` / `Contradicted` / `Stale` (see `server/src/knowledge/types.rs` lines 73-89).
|
|
|
|
Sprint 2 implementation only uses `Active`. But content must plan for Sprint 3 contradiction detection. Define:
|
|
|
|
- **What triggers Contradicted state:** Conflict between `DirectObservation` and `ToldBy` source on the same FactId or EntityKnowledge attribute. Example: Kael tells smuggler he's meeting partner Hael, but smuggler sees Kael meeting unknown contact in B-7.
|
|
- **Content requirements for contradiction arcs:** Each FRIEND NPC (D-034) needs at least one Contradicted trigger. List the 2 primary contradictions for v0.1 (Kael for smuggler, Sera for detective).
|
|
- **Stale handling:** Note that Stale is set by decay system (default: 3600 ticks = 6 game-hours per D-041), not by content. Content should assume Direct observation downgrades to KnowsDetails → KnowsOf → Suspects over time if not refreshed.
|
|
|
|
### 5. Integration with D-035 Tag Taxonomy
|
|
|
|
The `prerequisite` tag on monologue lines (D-035) references FactIds. Show 5-10 example monologue prerequisites using the vocabulary you've defined:
|
|
|
|
```yaml
|
|
# Example format (do not include in final document — reference only)
|
|
- id: sova_m_001
|
|
character: smuggler
|
|
trigger: observe_npc
|
|
prerequisite:
|
|
knows_of: "contraband.ring_exists"
|
|
entity:
|
|
target: kael_davan
|
|
min_confidence: KnowsOf
|
|
text: "Kael's moving with purpose. Shift doesn't start for another hour."
|
|
```
|
|
|
|
Define which FactIds map to which monologue triggers (per D-035: enter_location, observe_npc, hear_sound, observe_anomaly, post_conversation, discover_evidence, witness_interaction, time_idle, return_visit).
|
|
|
|
## Type Definitions to Conform To
|
|
|
|
Read `server/src/knowledge/types.rs` for canonical struct definitions. Key types:
|
|
|
|
- `FactId(String)` — lines 21-25
|
|
- `KnowledgeConfidence` enum — lines 28-67
|
|
- `KnowledgeState` enum — lines 73-89
|
|
- `KnowledgeSource` enum — lines 95-107
|
|
- `RelationshipState` enum — lines 117-140
|
|
- `EntityKnowledge` struct — lines 145-165 (note `known_attributes: BTreeMap<String, String>` at line 164)
|
|
- `FactKnowledge` struct — lines 169-179
|
|
- `KnowledgeGraph` component — see full definitions at `docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md` lines 320-520
|
|
|
|
## Good Vocabulary Entries Look Like This
|
|
|
|
**FactId example (good):**
|
|
```
|
|
investigation.manifest_discrepancy
|
|
- Suspects: "The cargo manifests don't add up"
|
|
- KnowsOf: "Dock worker signatures don't match logged shifts"
|
|
- KnowsDetails: "Kael signed for 18 containers on a day he was off-shift"
|
|
```
|
|
What makes this good: specific, maps to confidence levels, ties to investigation mechanic, references concrete NPC (Kael).
|
|
|
|
**FactId example (bad):**
|
|
```
|
|
smuggling.general
|
|
- KnowsOf: "There's smuggling happening"
|
|
```
|
|
What makes this bad: vague category, no confidence progression, no mechanical hook, too generic.
|
|
|
|
**EntityKnowledge attributes example (good):**
|
|
```yaml
|
|
kael_davan:
|
|
name: "Kael Davan"
|
|
role: "dock_worker"
|
|
faction: "ring_member"
|
|
relationship_type: "colleague"
|
|
trust_level: "high"
|
|
routine_pattern: "shift_worker"
|
|
behavior_flags: "reliable, quiet"
|
|
secret_held: "meeting unknown contact in B-7, not partner Hael"
|
|
secret_confidence: "Suspects"
|
|
tell_observed: "avoids eye contact when Hael is mentioned"
|
|
contradiction_flagged: "no"
|
|
```
|
|
What makes this good: complete identity, behavioral hooks, secret with confidence level, observable tell, ties to THE FRIEND arc.
|
|
|
|
**RelationshipState transition example (good):**
|
|
```
|
|
Smuggler + Kael Davan:
|
|
Initial: Friendly (colleague, trusted, high trust_level)
|
|
Trigger: observe Kael entering B-7 at off-hours → PersonOfInterest
|
|
Monologue: "Kael's here? He's not on shift. And he's avoiding the main corridor."
|
|
Progression: PersonOfInterest → contradiction detected (sees Kael with unknown contact, not Hael) → Contradicted state set → Hostile
|
|
```
|
|
What makes this good: clear initial state, specific trigger, ties to monologue, maps to THE FRIEND arc beats (D-034, D-039).
|
|
|
|
## Dependencies and Constraints
|
|
|
|
**Blocks:**
|
|
- #309 (Knowledge state vocabulary for v0.1) — Mellanie cannot write monologue prerequisites until this vocabulary exists
|
|
- #299 (Opening hook content — smuggler)
|
|
- #300 (Opening hook content — detective)
|
|
|
|
**Requires:**
|
|
- D-041 (Knowledge Graph Data Model) — read `decisions/architecture.md` lines 117-134
|
|
- D-034 (THE FRIEND) — read `decisions/content.md`, provides Kael Davan and Sera Venn as reference NPCs
|
|
- D-035 (Tag taxonomy) — read `decisions/content.md`, defines `prerequisite` tag format
|
|
- D-036 (Sova Transit District) — read `decisions/content.md`, provides setting context
|
|
- D-037 (Contraband specification) — read `decisions/content.md`, defines what the ring is smuggling
|
|
- D-028 (Dialogue architecture) — read `decisions/content.md`, defines access tiers that map to confidence levels
|
|
|
|
**Constraints:**
|
|
- v0.1 scope only — 15 NPCs, 3 social sites (Logistics Hub, Bar, Ring spaces per D-027)
|
|
- No procedural generation of FactIds — all must be hand-authored and stable across playthroughs
|
|
- FactId strings must be machine-parseable (no spaces, lowercase, dot-separated)
|
|
- Attribute keys must be consistent across all EntityKnowledge entries (BTreeMap keys are strings, but use the same keys for the same concepts)
|
|
- Sprint 2 server implementation only uses `Active` state and `DirectObservation` source — but vocabulary must plan for Sprint 3 expansion
|
|
|
|
## Deliverable Format
|
|
|
|
Markdown document at `docs/design/knowledge-vocabulary-v0.1.md` with sections:
|
|
|
|
1. **FactId Catalog** — table with category, FactId, confidence progressions, mechanical purpose
|
|
2. **EntityKnowledge Attribute Keys** — table with key name, type, purpose, example values
|
|
3. **Example EntityKnowledge Entries** — 3-5 complete examples for v0.1 NPCs
|
|
4. **RelationshipState Transition Triggers** — table with transition, trigger condition, example scenario
|
|
5. **Contradiction Patterns for v0.1** — 2 concrete THE FRIEND contradictions (Kael, Sera)
|
|
6. **Monologue Prerequisite Examples** — 5-10 lines showing FactId → monologue mapping
|
|
7. **Integration Notes** — how this vocabulary feeds into D-035 tag taxonomy and dialogue authoring
|
|
|
|
Keep it practical. This is a reference document for Mellanie's authoring work and Gestalt's dialogue system implementation. No narrative prose — tables, bullet points, concrete examples.
|
|
|
|
## Key References
|
|
|
|
- `server/src/knowledge/types.rs` — type definitions
|
|
- `decisions/architecture.md` D-041 — knowledge graph architecture
|
|
- `decisions/content.md` D-034 — THE FRIEND NPC profiles
|
|
- `decisions/content.md` D-035 — tag taxonomy and prerequisite format
|
|
- `decisions/content.md` D-036 — Sova Transit District setting
|
|
- `decisions/content.md` D-037 — contraband specification
|
|
- `docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md` — full design context
|
|
|
|
Estimate: 0.5 day. Unblocked — start immediately.
|