settled-reach/docs/sprints/sprint-2/copy.md

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 2 — Copy Briefing	Knowledge vocabulary definition, FactId categories, entity-attributes keys	sprint	archived	2	copy

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:

# 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):

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.