From 5c7d546f482fb4f1556c5d90f51d415dcc271587 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 12 Feb 2026 01:26:53 +0100 Subject: [PATCH 1/2] chore(config): add new team branches to protected list Add copy, audio, visual, ci to protected branches in CLAUDE.md. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index acd32bb7d..fbabd6c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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) From 715c7e16abf552c9605330cf8d23413b8608aebf Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 12 Feb 2026 01:31:00 +0100 Subject: [PATCH 2/2] docs(sprints): add copy team briefing for Sprint 2 Sprint briefing for #368 (knowledge vocabulary for v0.1 content). Defines FactId categories, known_attributes keys, and RelationshipState transition patterns the copy team needs to deliver. Co-Authored-By: Claude Opus 4.6 --- db/commonwealth.db | Bin 274432 -> 274432 bytes docs/sprints/sprint-2/copy.md | 240 ++++++++++++++++++++++++++++++++++ 2 files changed, 240 insertions(+) create mode 100644 docs/sprints/sprint-2/copy.md diff --git a/db/commonwealth.db b/db/commonwealth.db index 753152b3a54e0c55c527bae9f34e64b154ea52c6..e35435baeb6321fedda7c6492fa77d0e990f8839 100644 GIT binary patch delta 404 zcmZp8AkY9rEsQNpTbS7d82Pue3owT(!Ra4_nH?BoryGhe>#(pcWQdy_C=j)M zw+OS_Z+XTv1|9|zW(E`9`#k5kUvQ~&JZ3-6Hj6csF_$Hh>BvM!5#c7irc{0gaYp~9 zdSzL021a9JhUw4cSRQaASv38OJd2jBk%EDNm65rXsU_c426mvEnu441_!&f*qMN-% zw~I)y2s2KMnSMbV*@K=v*i4ON}vtXImKE2Y)_J8ab?`TN{U67ar-T478%Cv^1>`G zjN8KnSq?Hz|0%=rYpa}2LQ?tXlVcd delta 408 zcmZp8AkY9rEsQNpTbS7d7$vu}3owT_YM3}W0Go~AgFzfJhF^e-5r6#6SGN!UFWC)%d zDB!<+w+OS_Z+T`31|G(69=@x*_gRv8elmtL%X8o2TE&^f!NJbSTCzD%z?^Zrx)jSn zMs@}U1`yuFxq74_Lt-pT3omMPA0l#K^$NOxM6j*AQrnp%u`H#s*wKcNeg4*v_uNa*2s? Z!}eQBEZ11Ld6=b{pf2COTb;#~0{|udXC?pu diff --git a/docs/sprints/sprint-2/copy.md b/docs/sprints/sprint-2/copy.md new file mode 100644 index 000000000..9b81a76cb --- /dev/null +++ b/docs/sprints/sprint-2/copy.md @@ -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` (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` 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.