Merge remote-tracking branch 'origin/main' into copy
This commit is contained in:
@@ -105,7 +105,7 @@ Key rules:
|
||||
- **All flags must be explicit** — omitting `--login` or `--repo` triggers interactive prompts that crash in Claude Code (no TTY)
|
||||
- **Use `--output simple`** for machine-readable output (no table borders)
|
||||
- **`tea pr reject` does not work on your own PRs** — use `tea comment` instead
|
||||
- **Never delete protected branches:** `main`, `maintenance`, `server`, `client` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.
|
||||
- **Never delete protected branches:** `main`, `maintenance`, `server`, `client`, `copy`, `audio`, `visual`, `ci` are protected on Gitea. Do not use `tea pr clean`, `git push --delete`, or `git branch -D` on these branches.
|
||||
|
||||
### File conventions
|
||||
- Decisions: domain files in `decisions/` (see `decisions/README.md` for index)
|
||||
|
||||
Binary file not shown.
@@ -0,0 +1,240 @@
|
||||
# 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 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:**
|
||||
- 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.
|
||||
Reference in New Issue
Block a user