From f63691069c589d7467086837294dc7f842c0a1f8 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Sat, 28 Feb 2026 13:25:22 +0100 Subject: [PATCH] docs(docs): split questions.md into per-domain files Mirror the D-record pattern: questions.md becomes an index, full question content moves to questions-architecture.md, questions-perception.md, questions-content.md, questions-scope.md. Also incorporates final Sprint 22 team findings into Q-053/Q-054: - Q-053: transit map as incidental discovery surface, confidence signal, boards as entitlement map (Paula round 3) - Q-054: stateless DiagramData renderer architecture, annotation event model (Gestalt round 3) Corrects question counts: 16 resolved, 4 partially resolved, 34 open (previously undercounted). Co-Authored-By: Claude Opus 4.6 --- decisions/README.md | 6 +- decisions/questions-architecture.md | 88 ++++++ decisions/questions-content.md | 178 ++++++++++++ decisions/questions-perception.md | 104 +++++++ decisions/questions-scope.md | 91 ++++++ decisions/questions.md | 436 ++-------------------------- 6 files changed, 491 insertions(+), 412 deletions(-) create mode 100644 decisions/questions-architecture.md create mode 100644 decisions/questions-content.md create mode 100644 decisions/questions-perception.md create mode 100644 decisions/questions-scope.md diff --git a/decisions/README.md b/decisions/README.md index d589e5eec..3dc26335d 100644 --- a/decisions/README.md +++ b/decisions/README.md @@ -15,7 +15,11 @@ Cross-domain decisions live in one file with cross-reference notes in related fi | [content.md](content.md) | NPC, dialogue, templates | D-023, D-024, D-025, D-028, D-029, D-032, D-034, D-035, D-036, D-037, D-050, D-062, D-063, D-064, D-074, D-075, D-084, D-090, D-092, D-093, D-095, D-098, D-104, D-105, D-107 | | [scope.md](scope.md) | Game concept, prototype | D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027, D-038, D-039, D-051, D-053, D-065, D-087, D-089, D-091 | | [process.md](process.md) | Team, workflow | D-004, D-021, D-022, D-040 | -| [questions.md](questions.md) | Open questions | Q-001 through Q-050 | +| [questions.md](questions.md) | Open questions (index) | Q-001 through Q-054 | +| [questions-architecture.md](questions-architecture.md) | Technical questions | Q-001, Q-006, Q-009, Q-018–Q-023, Q-029, Q-030, Q-046 | +| [questions-perception.md](questions-perception.md) | Observation questions | Q-003, Q-014, Q-016, Q-024–Q-026, Q-051, Q-053, Q-054 | +| [questions-content.md](questions-content.md) | Narrative questions | Q-010, Q-012–Q-015, Q-017, Q-028, Q-031, Q-033, Q-040–Q-050, Q-052 | +| [questions-scope.md](questions-scope.md) | Scope questions | Q-002, Q-004, Q-005, Q-007, Q-008, Q-011, Q-027, Q-032, Q-034–Q-039 | | [rejected.md](rejected.md) | Rejected alternatives | R-001 through R-010 | ## Querying Decisions diff --git a/decisions/questions-architecture.md b/decisions/questions-architecture.md new file mode 100644 index 000000000..42b6e8aa9 --- /dev/null +++ b/decisions/questions-architecture.md @@ -0,0 +1,88 @@ +# Open Questions — Architecture + +Technical foundation questions: engine, protocols, data structures, performance, save/load. + +--- + +### Q-001: Game engine selection +- **Status:** Resolved → [D-020](architecture.md#d-020-engine-and-architecture-selection--godot-client--rust-simulation-via-subprocessipc) + +### Q-006: Multiplayer or single-player only? +- **Status:** Resolved → [D-009](architecture.md#d-009-multiplayer---design-for-it-build-single-player-first) + +### Q-009: Time system +- **Status:** Resolved → [D-031](architecture.md#d-031-time-system--game-clock-and-day-phases) + +### Q-018: Shadowcasting algorithm selection +- **Status:** Resolved → [D-035](perception.md#d-035-symmetric-shadowcasting-albert-ford-selected-for-los-computation) +- **Question:** Which line-of-sight algorithm should be used? Symmetric shadowcasting (Albert Ford) vs recursive shadowcasting. Both are proven but differ in symmetry properties (symmetric: if A sees B, then B sees A) and implementation complexity. Requires benchmarking at 150x150 map scale with 30 entities to validate performance within 100ms tick budget. +- **Context:** D-011 mandates LOS shadowcasting for fog of perception. Architecture review identified this as unspecified (audit section 2.2). Critical for Sprint 2 perception pipeline. +- **Assigned to:** Tyre, Dudley +- **Source:** Architecture Review Audit 2026-02-11 + +### Q-019: Entity ID stability strategy +- **Status:** Partially resolved → [D-041](architecture.md#d-041-knowledge-graph-data-model) +- **Resolution:** Server-side: `StableEntityId` component + `EntityRegistry` resource provides bidirectional `StableId(u64) <-> Entity` mapping. StableId assigned once at entity spawn, never changes, persists across save/load. Knowledge graphs reference StableId, not bevy Entity. Client-side mapping (Godot StableId -> scene node lifecycle) remains open. +- **Remaining:** Client-side entity lifecycle management, scene node mapping strategy. +- **Date partially resolved:** 2026-02-11 +- **Assigned to:** Tyre, Dudley (client-side portion) +- **Source:** Knowledge Graph & Information Boundaries Workshop + +### Q-020: Multi-entity collision resolution +- **Status:** Open +- **Question:** When two NPCs attempt to move to the same tile on the same tick, what is the resolution policy? Options: first-write-wins (deterministic with system ordering), both fail (conservative), priority-based (e.g., player > NPC, Active tier > Background tier). +- **Context:** D-012 defines tile collision. WalkabilityMap exists (server/src/simulation/movement.rs) but handles single-entity validation. Architecture review identified multi-entity collision as unspecified. +- **Assigned to:** Gestalt, Dudley +- **Source:** Architecture Review Audit 2026-02-11 + +### Q-021: Tick budget overflow policy +- **Status:** Open +- **Question:** When a simulation tick exceeds the 100ms budget, what happens? Options: (1) slow down real-time and preserve determinism (tick completes fully before next), (2) skip ticks and break determinism, (3) cap work per tick and defer to next tick. Must align with D-010 principle 4 (deterministic simulation). +- **Context:** D-026 defines 100ms tick budget for Active tier at 10 tps. Architecture review consensus recommendation proposes "slow real-time, don't skip ticks." Needs formal decision. +- **Assigned to:** Tyre, Dudley +- **Source:** Architecture Review Audit 2026-02-11 + +### Q-022: NPC pathfinding cache eviction +- **Status:** Open +- **Question:** With 80 Active-tier NPCs each caching ~3 pathfinding routes, the cache holds ~240 paths. What is the eviction policy? LRU? Time-based expiration? Fixed size per NPC? How are paths invalidated when walkability changes (doors lock, areas become restricted)? +- **Context:** Architecture review identified pathfinding as MEDIUM gap (audit section 2.2). Cache management needs specification regardless of algorithm choice. +- **Assigned to:** Tyre, Dudley +- **Source:** Architecture Review Audit 2026-02-11 + +### Q-023: Debug visualization scope +- **Status:** Open +- **Question:** What information should the debug overlay display? Candidates: LOS rays, pathfinding waypoints, vision cones, information boundary tags (who knows what), tick timing breakdown, spatial partition grid cells. Dev-only tool, or accessible for mod development? +- **Context:** Architecture review (Troblum) identifies debug visualization as missing operational infrastructure. Needed for debugging perception system, information boundaries, and performance issues. +- **Assigned to:** Tyre, Stig +- **Source:** Architecture Review Audit 2026-02-11 + +### Q-029: Save file format design +- **Status:** Open +- **Question:** What should the long-term save file format look like? Key considerations: + 1. **Versioning and migration:** How do saves survive across game versions? Schema evolution strategy (field additions, renames, removals). Should saves embed a version number and run migrations on load? + 2. **Compression:** Raw MessagePack vs compressed (zstd, lz4)? Tradeoff between save/load speed and file size. SaveStateV1 is already MessagePack — does that carry forward? + 3. **Integrity:** Checksums or signatures to detect corruption? CRC32 header? + 4. **Metadata header:** Should the file have a readable header (game version, save date, play time, character name) that the loading screen can read without deserializing the full save? + 5. **Determinism:** D-010 requires deterministic simulation. Can saves capture enough state to resume deterministically, or is approximate resume acceptable? + 6. **Modding:** Should the format be documented for mod authors? Does it need extension points? + 7. **Cloud sync:** Any considerations for Steam Cloud or similar? File size limits? +- **Context:** Sprint 19 implements a quick-and-dirty save format (D-085 per-game directories, MessagePack serialization from SaveStateV1). This question tracks the thorough design pass for production quality. +- **Assigned to:** Tyre, Dudley +- **Source:** Team Leader directive (Sprint 19 planning) + +### Q-030: Seed configuration schema +- **Status:** Open +- **Question:** What artifact records all randomizer decisions at game start? The wiki-review workshop proposed a `seed-state.yaml` capturing: world seed, character selection, pool draws (Tier 1 modules, FRIEND selection, contraband variant), template assignments, NPC trait rolls, triangle configurations, and entanglement pattern. Ticket #394 (seed configuration schema design) exists but the design is open. +- **Assigned to:** Tyre, Gestalt +- **Source:** Wiki Review Workshop + v0.1 Content Scoping Workshop + +### Q-046: Departure schedule model — departure windows as generator output for docked vessels +- **Status:** Resolved → D-108 (MobileChunk Specification) +- **Resolution:** `scheduled_departure: Option` in `Docked` state is mandatory generator output. Vessels without departure schedules are an error state. The `Docked` struct must include `docked_since: SimTick` and `scheduled_departure: Option` — these fields must be added at implementation time (absent from Tyre's Round 4 canonical struct). +- **Date resolved:** 2026-02-27 +- **Source:** Generator Architecture Workshop (#562) +- **Assigned to:** Tyre + Miri + +--- + +*12 questions (6 resolved, 1 partially resolved, 5 open). Last updated: 2026-02-28.* diff --git a/decisions/questions-content.md b/decisions/questions-content.md new file mode 100644 index 000000000..cb054567d --- /dev/null +++ b/decisions/questions-content.md @@ -0,0 +1,178 @@ +# Open Questions — Content + +Narrative, NPCs, dialogue, templates, setting, worldbuilding, and storyteller mechanics. + +--- + +### Q-010: Storyteller AI design +- **Status:** Not yet discussed +- **Question:** How does the Rimworld-style storyteller work? What are the pacing rules? How much structural randomness vs dramatic randomness? +- **Assigned to:** Gestalt, Nigel + +### Q-012: Generation expansion method for dialogue +- **Status:** Open +- **Question:** How does the 4x generation expansion pass work? LLM-based, template-based, or rule-based? Affects how base lines are authored — LLM needs style-strong anchors; rules need substitution patterns. +- **Assigned to:** Gestalt, Mellanie +- **Source:** Content Gap Analysis Workshop (Mellanie R2) + +### Q-013: Line previewer temporal progression +- **Status:** Open +- **Question:** How does the line previewer (#193) handle THE FRIEND's multi-visit contradiction arc? Needs sequence mode to simulate interaction progression over multiple encounters. +- **Assigned to:** Gestalt, Dudley +- **Source:** Content Gap Analysis Workshop (Mellanie R2) + +### Q-015: Generation expansion for THE FRIEND content +- **Status:** Open +- **Question:** Does the 4x generation expansion apply to THE FRIEND's custom lines, or are all ~70-100 lines per FRIEND hand-authored? Recommendation: no expansion on FRIEND lines — risk of flattening hand-crafted voice. +- **Assigned to:** Mellanie, Gestalt +- **Source:** Content Gap Analysis Workshop (Ozzie R2, Gestalt R2) + +### Q-017: Triangle pressure threshold +- **Status:** Open +- **Question:** Triangles need a numeric pressure value that increases based on events. When it crosses a threshold, `confrontation` situation activates. What events increase pressure? What's the threshold? +- **Assigned to:** Gestalt, Paula +- **Source:** Content Gap Analysis Workshop (Gestalt R2) + +### Q-028: Collision-resistant line IDs for auto-generated NPCs +- **Status:** Resolved → [D-084](content.md#d-084-dual-namespace-line-id-scheme--role-pool--instance-override) +- **Resolution:** The collision problem is mostly already solved by the role-pool architecture: `dock-worker_d_###` lines are shared content for all instances of the role, not per-instance IDs. A true collision (two distinct authored lines sharing the same ID) cannot occur with one file per role. For the edge case of authored instance-specific content, a role-slug + zero-padded generation counter suffix produces `dock-worker-07_d_001`. Counter is seeded-deterministic. No schema change, no migration. Hand-authored NPCs unchanged. +- **Closed by:** Gestalt (Sprint 18, #544). 2026-02-25. +- **Ticket:** #544 +- **Assigned to:** Gestalt, Tyre +- **Source:** Sprint 16 PR #59 review discussion (2026-02-23) + +### Q-031: Combined content style guide +- **Status:** Open +- **Question:** Should the project have a single combined content style guide merging Paula's tier templates, Mellanie's voice conventions, Gestalt's mechanical constraints, and Miri's regional guide? The wiki-review workshop proposed this as a deliverable but it was never authored. What format, who owns it, and does it block content authoring? +- **Assigned to:** Mellanie, Paula +- **Source:** Wiki Review Workshop R2 + +### Q-033: Three-system NPC architecture +- **Status:** Open +- **Question:** Should NPCs be formally composed from 9 thematic patterns (FRIEND, MIRROR, ANCHOR, GHOST, CATALYST, THRESHOLD, REMNANT, SYSTEM, NOBODY) x 6 functional motivations (HANDLER, WITNESS, TURNCOAT, CIVILIAN, OPERATOR, SKEPTIC)? D-024 defines 10 axes + combat but predates this refined system. The wiki-review workshop produced a full composition matrix with drama ratings and forbidden combinations. Does this supersede D-024 or extend it? +- **Assigned to:** Gestalt, Paula +- **Source:** Wiki Review Workshop R4 + +### Q-040: Gate dual-use topology — freight and commuter on shared span gate infrastructure +- **Status:** Resolved → D-093 (gate cluster zone spec), D-095 (span gate dual-use windows) +- **Question:** System span gates serve both freight and commuter traffic (one gate per system). How does this work physically? Is it one gate aperture with scheduling (freight window vs. passenger window), or parallel lanes (separate apertures for freight and passenger flows)? What does the gate facility look like from the inside — a single large bay or divided infrastructure? +- **Layout implication:** Affects the gate cluster spatial design in the Transit District — the gate cluster must accommodate both freight staging and passenger throughflow, possibly at different times of day. +- **Assigned to:** Miri +- **Source:** Station District Layout Workshop (#153), Round 2. Surfaced by lead correction to Miri's S-02 (commuter transit ≠ second external gate). +- **Cross-reference:** D-036 (Sova setting), Q-036 (district skeleton as generator output) + +### Q-041: Interstellar travel mechanics — horizon stations and gate architecture +- **Status:** Resolved → D-095 (horizon stations: alien-built, 4–8 apertures, Oort-cloud, "The Ring"; sequential hop travel) +- **Question:** A system needs MORE than one horizon gate for multi-hop connectivity (one gate allows only 1:1 connections). Lead proposal (Round 3): **Horizon stations** — orbital installations at Oort-cloud distance, partially or wholly understood ancient alien technology, self-maintaining (Mass Effect relay/Citadel analog). Each horizon station holds a FIXED number of active and inactive horizon gates. Some systems may only have one hop to an orbital customs station with no direct planet-side span gate access. Remaining questions: How many gates per horizon station? What determines which gates are active vs. inactive? Is the travel instantaneous or traversal-based? What is "The Ring" (the orbital horizon station) like as a physical space? +- **Assigned to:** Miri +- **Source:** Station District Layout Workshop (#153), Round 2. Lead correction in Round 3: single-gate-per-system model insufficient for multi-hop travel; horizon station model proposed. +- **Cross-reference:** D-036 (Sova setting), Q-039 (gate topology generation), Q-040 (gate dual-use topology) + +### Q-042: Intra-system transport networks — passenger vs. freight, vehicles and modes +- **Status:** Partially resolved → D-095 (span gates at star/planetary level; horizon stations at Oort distance). Intra-system hab-to-hab transit remains open. +- **Question:** How do people and goods move within a star system (between orbital stations, planetary surfaces, and other in-system facilities)? Are there two separate networks (passenger transport and freight transport) or one shared network? What are the vehicle types and transit modes? How does intra-system transit interact with the span gate at the system's hub station? +- **Assigned to:** Miri +- **Source:** Station District Layout Workshop (#153), Round 2. Flagged by lead as transport lore requiring formal tracking. +- **Cross-reference:** D-036 (Sova setting), Q-043 (station internal transit) + +### Q-043: Station internal transit — intra-station transport system between districts +- **Status:** Resolved → D-095 (The Loop: 6-district tram, 4-minute Residential Core → Transit District; transit platform is bar-side encounter node) +- **Question:** What is the intra-station transport system on Station Sova? How do workers commute between districts (e.g., Residential Core → Transit District)? Is it a train, tram, shuttle, or pressurised corridor? What is the travel time and frequency? Where does the transit stop sit within the Transit District — gate-cluster-adjacent (workers arrive near freight operations) or bar-side-adjacent (workers arrive near their social space)? +- **Layout implication for #153:** The Transit District must include an internal transit stop. Its position within the district affects NPC traffic patterns and the district entry topology. This is the active T-03b question for Round 2/3 of the Station District Layout Workshop. +- **Assigned to:** Miri +- **Source:** Station District Layout Workshop (#153), Round 2. Arose from lead correction: commuter transit = internal station transit, not a second external gate. +- **Cross-reference:** D-036 (Sova setting), Q-042 (intra-system transport networks), S-02 revision + +### Q-044: Gate-train integration — do transport vehicles use gates directly or transfer on each side +- **Status:** Resolved → D-093/D-095 (gates are pedestrian/cargo-only; passengers transfer via gate concourse → transition corridor → transit platform; no direct gate-to-tram connection) +- **Question:** If trains or shuttles are the intra-system or intra-station transit mode, do they use the span gate directly (a train enters the gate and exits at the destination, carriages and all)? Or are the gates pedestrian/cargo-only, requiring passengers and freight to transfer to separate transport on each side? What does this imply for gate terminal design — does it need platforms, or just processing space? +- **Assigned to:** Miri +- **Source:** Station District Layout Workshop (#153), Round 2. Flagged by lead as transport lore requiring formal tracking. +- **Cross-reference:** Q-040 (gate dual-use topology), Q-043 (station internal transit) + +### Q-045: Axis 11 — Network Footprint NPC tag +- **Status:** Open +- **Priority:** High +- **Question:** Should the NPC model (D-024, 10 axes) gain an 11th axis: `network_footprint: Option` for NPCs who are locally insignificant in appearance but carry network-significant information or are relevant to external actors? Default `None` for procedural NPCs. Explicitly set for authored scenario NPCs. This would enable the storyteller to identify locally-invisible but network-critical nodes without breaking the NPC's mundane character. +- **Context:** Raised during Generator Architecture Workshop (#562). The Ysabel Vorn litmus test (4.5/5 playstyle hooks, Backwater/Moderate setting) demonstrated that locally-insignificant NPCs can be key network nodes. Without this field, the generator has no mechanism to flag them to the storyteller. +- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §NPC Model. +- **Assigned to:** Miri + +### Q-047: Mobile environment social arc — structural representation of journey timeline +- **Status:** Open +- **Priority:** Medium +- **Question:** How is the social arc of a mobile environment journey (BoundedLinear / BoundedMobile) represented structurally? The journey has a beginning (boarding, strangers), middle (established dynamic), and end (departure, relationship crystallized). What game structures capture this timeline and enable the storyteller to intervene? Does `TransitSocialModifier` need a journey-phase field? +- **Context:** Ozzie's player experience requirement from Generator Architecture Workshop (#562): "the journey must have a social arc — not just social presence." The stage+cast framing is correct; the formal structural representation is unspecified. +- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §Open Questions. +- **Assigned to:** Miri + Gestalt + +### Q-048: DramaDensity enum naming — 3-level vs 5-level +- **Status:** Open +- **Priority:** Low +- **Question:** The Round 4 struct uses `Quiescent / Active / Intense` (3 levels). Round 3 proposed `Zero / Low / Medium / High / Flashpoint` (5 levels). Which should be canonical? Nigel's position: `Flashpoint` should be preserved as a distinct peak value — it is the storyteller's maximum-pressure instrument and should not collapse into `Intense`. If 3 levels are chosen for implementation simplicity, `Flashpoint` should still be the distinct peak name, not `Intense`. +- **Context:** ComplexityTier → DramaDensity ceiling (established): Full → any intensity; Moderate → Active max; Minimal → Quiescent max; Empty → Zero only. Naming must be consistent with these ceiling values. +- **Source:** Generator Architecture Workshop (#562), Rounds 3–4. `docs/workshops/generator-architecture/workshop-outcomes.md` §Open Questions. +- **Assigned to:** Tyre + Gestalt + +### Q-049: ObjectTag vocabulary co-maintenance — Miri and Araminta shared dependency +- **Status:** Open +- **Priority:** Medium +- **Question:** The `ObjectTag` vocabulary must be co-maintained between Miri's `HeritageGrammarOverlay` (cultural grammar, Rust struct) and Araminta's asset categorization (visual expression, TOML files). What is the governance model? Who owns the canonical tag list? How are additions and deprecations coordinated? Does the vocabulary live in the Rust struct definition or in a shared data file? +- **Context:** If the vocabulary diverges, the generator will reference tags that don't exist in asset categories, or assets will be authored that the grammar never references. This is a silent correctness failure. +- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §D-READY-9. +- **Assigned to:** Miri + Araminta + +### Q-050: Assassination difficulty synthesis — formal spec combining stored baseline with on-demand computation +- **Status:** Open +- **Priority:** Medium +- **Question:** Formal specification needed for the synthesis combining stored cultural baseline (`DerivedDistrictAnalysis` on Phase 1 skeleton) with on-demand runtime computation for player-facing assessment. Key constraint from Miri: **on-demand computation is display-only** — all game logic (tactical triangle instantiation, guarantee audit) uses the Phase 1 `DerivedDistrictAnalysis` value. The on-demand computation is subordinate to the stored baseline, not a replacement. +- **Context:** Minor tension between Gestalt's "computed entirely on demand" position and Miri's "stored cultural baseline" position. Synthesis accepted by both participants in Generator Architecture Workshop (#562); formal spec needed for implementation. +- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §Open Questions. +- **Assigned to:** Gestalt + Miri + +### Q-052: Storyteller hint delivery — parallel diegetic channels when player does not act +- **Status:** Open (Sprint 22 analysis complete, awaiting implementation scoping) +- **Priority:** High +- **Question:** When a TriangleActivated event fires and the player does not investigate, what mechanisms create conditions for discovery? How do these scale from v0.1 (1-2 triangles) to the full game (300 worlds, 10+ simultaneous triangles, 8 archetypes)? +- **Core design principle:** "The storyteller is not delivering messages — it is creating conditions under which the player's existing relationships, existing investments, and existing world naturally produce signal." Player inaction is a valid outcome, not an error state. Consequences happen; the world moves on. +- **Channel inventory (ranked by deniability — least nudge-like first):** + 1. **Behavioral tell escalation** — activated triangle NPCs exhibit more pronounced tells (D-024 axis 9). Always active, proximity-gated. Feels like the world being alive. Scales infinitely, zero authoring per triangle. + 2. **Environmental change** — something physically different at the triangle location (locked door, moved cargo, light on at wrong hour). Archetype-agnostic: engineer reads the system fault, diplomat reads the guard rotation, merchant reads the sealed bay. Infinite scale, zero authoring per triangle. + 3. **Ambient sound cue** — audible change in the triangle zone (hushed conversation, footsteps at unusual time, a door that was open now shut). Uses D-018 three-range system. Proximity-gated. + 4. **Overheard NPC conversation** — secondary NPCs gossip about the activated NPC's changed behavior. Fires when two NPCs share a scene in a social site. Scales with the social simulation, not with authoring. Constraint: the NPC speaks from their own concerns ("He owes me for last week's haul and now he's not answering"), never from narrative convenience ("I think something is wrong with Kael"). + 5. **Unprompted NPC remark** — a non-job-giver NPC proactively comments when the player approaches. Uses D-028 Layer 4 unprompted disclosure with `situation: [triangle_activated]`. + 6. **FRIEND message** — the FRIEND NPC (D-034) reaches out. Structurally unique: when the FRIEND IS the triangle anchor (smuggler/Kael), the message is simultaneously the nudge and the tell — its timing, phrasing, and whether it sounds normal are the investigative data. Reserve for the triangle the FRIEND is directly connected to; degrades on overuse (one FRIEND per character = hard limit). + 7. **Internal monologue** — player character's inner voice notices something. Proximity-gated to triangle NPCs exhibiting tells. Character-specific voice (D-032, D-090). + 8. **Job-giver app message** — institutional backstop of last resort. Fires only if no other channel has produced player engagement. One per session maximum, for the single highest-engagement triangle only. Job-giver per archetype: smuggler = handler ("Dock 7, pickup, ask for Kael"), detective = Commission superior ("Welfare check, dock-level, concern logged by port authority"), engineer = fault log, diplomat = peer request, merchant = market signal. Three sender types: named NPC (personal), institution (semi-personal), automated system (impersonal). +- **Delivery model — parallel channels, not linear funnel:** + - All channels activate on TriangleActivated. The player encounters whichever their playstyle naturally intersects first. + - Channels have capacity, not triangles: monologue holds 1 thread (highest engagement wins), gossip holds 2-3, tells are unlimited. Lower-engagement triangles naturally get quieter channels — no starvation. + - App message has a long fuse; only delivers if no other channel has been "hit" (storyteller detects player engagement via any channel). Prevents the pattern from being predictable across playthroughs. + - Diegetic test for all channels: could you explain the output without reference to the activated triangle? If yes, diegetic. If no, quest marker. +- **Scaling properties (v0.1 → full game):** + - Channel priority inverts at scale. v0.1: authored channels (monologue, job-giver) dominate. Full game: universal channels (environmental, overheard, tells) are the foundation because they scale with the simulation, not with authoring. + - Job-giver coherence breaks if overused — handler sending player to 3 activated locations in one session becomes transparent. Backstop for highest-engagement triangle only. + - Hint adaptation: storyteller tracks `PlayerHintEngagement` — how often the player engages after each channel tier. Extends fuses and reduces probabilities as player demonstrates skill. Hours 1-5: full hints. Hours 15+: player reads the world by behavioral tells alone. "Not harder combat — a quieter, more trusting world." Resets per new playthrough. + - ~15-20 hour meta-awareness cap: beyond that, the game likely needs a complementary active system (case board, network map) the player reads rather than passively receives. Separate design problem, out of scope here. +- **Signal pollution gating:** + - Monologue: only when player is within proximity of a triangle NPC exhibiting tells. + - Gossip: only when the player initiates conversation with a connected secondary NPC. Passive, not pushed. + - FRIEND message: only if the FRIEND has a plausible in-world reason to reach out at this moment (established relationship cadence). + - Job-giver: once per session, backstop only. + - Environmental/tells: always active, no gating needed (they ARE the world). +- **Implementation implications:** + - Storyteller needs a `ChannelSet` per activated triangle tracking which channels have fired and whether the player has engaged. + - Post-activation state machine: `Activated → [channels live] → Resolved (player engages) | Consequences (timeout) | Expired`. + - NPC behavioral state changes need to register as conversation topics for social-network propagation (simulation feature, not content feature). + - App message content uses D-028 tagged line pools with new `situation: [app_message]` tag and sender-type sub-tag. Rendered in neural insert UI as message thread, not monologue overlay. +- **Content pipeline:** + - Universal channels (environmental, overheard, tells): zero per-triangle authoring. Build once as simulation features. + - Authored channels (monologue, FRIEND, job-giver): per-character/per-archetype investment. Layer on top as richness. + - Job-giver treated as authored feature shipping archetype by archetype, not universal system shipping once. +- **Context:** Raised during Sprint 22 storyteller scoping (#162). Analysis by Gestalt (systems) and Paula (narrative) across two rounds. +- **Cross-reference:** D-023 (storyteller activation), D-016 (monologue system), D-018 (three-range hearing), D-024 (NPC axes — tell system), D-028 (dialogue architecture), D-032 (separate monologue pools), D-034 (THE FRIEND), D-090 (character voice), #162 (storyteller module activation) +- **Assigned to:** Gestalt, Paula + +--- + +*19 questions (5 resolved, 1 partially resolved, 13 open). Last updated: 2026-02-28.* diff --git a/decisions/questions-perception.md b/decisions/questions-perception.md new file mode 100644 index 000000000..567c472b1 --- /dev/null +++ b/decisions/questions-perception.md @@ -0,0 +1,104 @@ +# Open Questions — Perception + +Player observation, information systems, UI surfaces, knowledge mechanics, and insert workspace. + +--- + +### Q-003: Art direction / presentation style +- **Status:** Further resolved for v0.1 via Content Gap Analysis Workshop. Araminta's v0.1 Visual Grammar proposal covers: entity color palette (D-033), zone-specific color palettes (3 zones with hex values), fog rendering (4 states), monologue presentation spec, insert dual-character variants. Long-term art direction beyond v0.1 remains open. +- **Remaining:** Long-term art direction, sprite replacement timeline, full visual identity. +- **Assigned to:** Araminta (lead) + +### Q-014: Audio timing with monologue chime +- **Status:** Resolved → [D-067](perception.md#d-067-recognition-chime-fires-at-onset-of-cognitive-delay) +- **Resolution:** Chime fires at ONSET of cognitive delay, not completion. 300-400ms duration, overlapping delay start. Chime is "unresolved" — opens a question, doesn't answer one. Sequence: hear/sense → chime plays → 0.6s delay begins → monologue text during delay → blob transitions to D-033 color → recognition complete. +- **Date resolved:** 2026-02-16 + +### Q-016: Knowledge hierarchy for monologue prerequisites +- **Status:** Resolved → [D-041](architecture.md#d-041-knowledge-graph-data-model) +- **Resolution:** 4-level hierarchy: `Suspects < KnowsOf < KnowsDetails < Direct`. Suspects = "something's off", gates initial investigation and vague monologue. KnowsOf = "X is involved in Y", gates topic-specific dialogue and peer-tier access. KnowsDetails = actionable detail, gates confrontation and secret-tier dialogue. Direct = currently in LOS, provides live position data. Maps to D-028 access tiers and D-035 prerequisite tags. +- **Date resolved:** 2026-02-11 +- **Source:** Knowledge Graph & Information Boundaries Workshop + +### Q-024: Gossip propagation timing +- **Status:** Resolved → [D-080](perception.md#d-080-npc-to-npc-knowledge-propagation) +- **Resolution:** Knowledge transfer occurs via a separate `transfer_npc_knowledge` Bevy system running `after(run_npc_conversations)`. Transfer fires once per conversation at conversation start (immediate during conversation, not queued). Rate: 1–3 facts drawn by recency. Trust-tier gated. See D-080 for full specification. +- **Closed by:** Knowledge Flow & NPC Information Boundaries Workshop — unanimous. 2026-02-24. +- **Source:** Knowledge Graph & Information Boundaries Workshop (Gestalt Round 1); resolved in Knowledge Flow & NPC Information Boundaries Workshop Round 2. + +### Q-025: Knowledge graph cap and eviction strategy +- **Status:** Resolved — no cap or eviction needed for v0.1/v0.2. Re-evaluation trigger: Active NPC count > 200 OR KG memory exceeds 50 MB. +- **Question:** At what point does an NPC's knowledge graph need entry eviction? What is the eviction policy? +- **Resolution (2026-02-24, confirmed by Knowledge Flow workshop):** Current analysis: ~14 KB per Active NPC KG (50 entities + 20 facts, D-041 budget). 80 Active NPCs = ~1.1 MB. 2,000 Background NPCs at 10 entries = ~5 MB. Total ~6 MB. With gossip propagation shipping in Sprint 17 (D-080, 1–3 facts per conversation): estimated ~12 MB peak at current NPC counts. Neither re-evaluation condition expected before v0.3. The existing decay system (`decay_knowledge` in `knowledge/events.rs`) downgrades confidence and marks entries Stale but does not remove them — correct behavior (preserves "I used to know X" for narrative). If eviction becomes necessary, simplest policy: on each decay pass, if entities.len() > MAX_ENTITIES, remove Stale entries with lowest last_updated_tick. BTreeMap makes this O(N). +- **Closed by:** Knowledge Flow & NPC Information Boundaries Workshop — Tyre, Gestalt, Dudley confirmed; Paula non-objection noted. 2026-02-24. +- **Source:** Knowledge Graph & Information Boundaries Workshop (Dudley Round 1, section 8.3). Architecture audit 2026-02-23. Workshop confirmation 2026-02-24. + +### Q-026: Contradiction detection algorithm +- **Status:** Resolved → [D-083](perception.md#d-083-contradiction-detection-pipeline) +- **Resolution:** Event-driven detection at KG write time in `observe_entity()`, using `ContradictionClaim` struct. Location contradiction is automatic (Sprint 17): position comparison + time window (CONTRADICTION_WINDOW_TICKS = 600). Attribute and fact contradiction are content-authored (Sprint 18). Both ToldBy and DirectObservation entries receive Contradicted state (epistemic neutrality). `ContradictionDetected` event → monologue with resolved display names → relationship shift → AnomalyMarker via existing pipeline. +- **Closed by:** Knowledge Flow & NPC Information Boundaries Workshop — unanimous on architecture. 2026-02-24. +- **Source:** Knowledge Graph & Information Boundaries Workshop (Gestalt/Paula Round 1); resolved in Knowledge Flow & NPC Information Boundaries Workshop Round 2. + +### Q-051: Speech bubble indicator over speaking NPCs +- **Status:** Open +- **Priority:** Low +- **Question:** Add a generic speech bubble icon above the head of any NPC that is currently speaking in a conversation. Consider reusing the per-character color coding from the dialogue log so the player can easily map speech bubbles to dialogue entries. +- **Context:** When multiple NPCs are nearby and the dialogue log is scrolling, it can be hard to tell who is speaking. A floating speech bubble icon (not the text itself — just the indicator) over the speaker's sprite would anchor dialogue to world position. Color-coding to match the dialogue log's per-character colors reinforces the mapping. +- **Assigned to:** Stig + Araminta + +### Q-053: Insert workspace boards — design philosophy and information architecture +- **Status:** Open (Sprint 22 analysis complete) +- **Priority:** High +- **Question:** How do boards function as the player's primary active information surface, and what design principles govern their behaviour across archetypes, game phases, and concurrent use? +- **Core design principle:** Boards are a **general-purpose communication layer** to the player, not a mechanic in themselves. The renderer is agnostic — it takes structured data and draws it. What creates a board, what populates it, and what its lifecycle is are decisions owned by the upstream system (quest, journal, navigation, business management, faction tracking, etc.), not the renderer. +- **Design principles established:** + 1. **Epistemology map, not truth map.** "The board maps the player's epistemology, not the game's truth." Nodes appear as the player encounters them. Connections are always the player's work. The board never reveals information the player hasn't acquired through gameplay. + 2. **Passive nodes, active edges.** Things appear automatically when observed/learned; relationships between them are the player's inference. This makes the board a thinking tool, not a checklist. + 3. **Multiple concurrent boards.** A character can be on an investigation while running a business while tracking a social network. Boards attach to whatever upstream system creates them — a quest, a business, a journal category, a transit network. The workspace presents them as tabs or equivalent navigation. + 4. **Archetype-specific readings.** Same diagram data, different professional questions. Detective reads evidence chains, smuggler reads trust networks, engineer reads system diagrams, diplomat reads faction leverage, merchant reads supply lines. The rendering primitive is identical; the upstream system determines what nodes and edges mean. + 5. **Cross-board convergence as discovery.** When the same node appears on multiple boards, that IS the discovery moment. Consistent visual identity (same icon, same colour) lets player recognition do the work — no automatic highlighting, no "this person appears on another board!" popup. The player connects the dots. + 6. **Monologue as diagram interaction surface.** When the player focuses a board node, the monologue system can fire character-specific commentary. "He was at both meetings" is monologue, not board UI. This connects the active information system (Q-053) to the passive hint system (Q-052). + 7. **Board as relationship with an information source.** Every board has a creator — the upstream system that owns the data and pushed it. The creator's framing shapes the initial state: initial nodes are their view of the situation, gaps are what they didn't know, chose not to include, or deliberately withheld. The gap between a board's initial state and its final state is the story the board tells. + 8. **Confidence signal as information asymmetry.** Nodes need a confidence state: initial nodes from the creator are unconfirmed (faint); player-observed nodes are confirmed (solid). The distinction between "what you were told" and "what you know" is the information asymmetry mechanic expressed at the board level. + 9. **Boards as entitlement map.** The boards in a player's workspace are a map of their information entitlements — which systems trust them with data, which factions include them in their information flows, which institutions grant them access. +- **Transit maps — core navigation mechanic:** + - Transit maps are boards whose upstream system is the navigation/transport layer, not the political geography layer. They respond to political geography (route closures, faction control) but their primary function is **how the player gets around**. + - Implementation: Network renderer with position-constrained layout mode (nodes pinned to world coordinates). Same rendering primitive as investigation boards (free layout mode), different layout constraint. + - Transit maps exist from day one as a live, simulation-fed surface — not a static reference image. + - **Archetype overlays are incidental discovery.** The smuggler's inspection-schedule annotation and the detective's jurisdiction boundary are visible through ordinary navigation, not special investigation mode. The player opens the map to travel and notices the secondary reading. Archetype depth surfaces through constant ordinary use. Design constraint: overlays must be subtle enough not to clutter the primary navigation function. + - **Highest-frequency convergence surface.** Because the transit map is opened constantly, it is the most likely place for board nodes and navigation context to appear together without the player looking for it. A location that is a node on any active board shows its consistent visual identity on the transit map — same glyph, same colour. Player recognition does the work. + - **Change over time is the political layer.** Because the map is used constantly, changes to it are noticed: a gate that was open is now restricted, an inspection checkpoint appeared on a familiar route. Infrastructure changes accumulate into a picture of what is shifting in the world — the conspiracy is visible in the map before it is visible in any individual NPC's behaviour. +- **Scaling properties:** + - v0.1: one or two board types (investigation + transit map) validate the rendering primitive and workspace navigation. + - Full game: boards proliferate naturally as upstream systems ship — business dashboards, faction maps, crew manifests, engineering schematics, social network visualisations, reference material (field guides, legal codes). + - Board count is not a design problem — it's a UX problem (workspace navigation, tab management, search/filter). The primitive scales inherently. +- **Context:** Raised during Sprint 22 planning. Initial framing included d2 syntax as in-game format; lead directed that d2 remains a dev tool only and is not involved in the in-game system. Analysis by Gestalt (systems) and Paula (narrative) across three rounds with multiple lead corrections. +- **Cross-reference:** Q-054 (rendering primitive data contract — the technical "how"), Q-052 (storyteller hint delivery — boards as the complementary active system), D-056/D-057 (insert diegetic conventions) +- **Assigned to:** Gestalt, Paula + +### Q-054: Insert workspace board — rendering primitive and data contract +- **Status:** Open +- **Priority:** High +- **Question:** What is the board rendering primitive and its data contract? A board is a **general-purpose structured information surface** rendered inside the insert workspace. The renderer is agnostic to data source — it takes structured data and draws it. Upstream systems (quests, journal, navigation, faction tracking, reference material, business management, or anything with structured data worth visualizing) are responsible for creating boards, populating them, and managing their lifecycle. The renderer does not know or care why a board exists. +- **Renderer architecture (Sprint 22 analysis):** + - The renderer is a **stateless display service**. It takes `DiagramData` and draws it. It has no opinion on why a board exists, what created it, or what the data means. + - Data contract: `DiagramData { id: DiagramId, diagram_type: Network | Flow | Table | Spatial, interaction_schema: InteractionSchema, annotations: Vec }` plus type-specific content (nodes/edges, rows/columns, layers). + - The renderer fires interaction events when the player clicks/hovers. Upstream systems handle those events. + - Player annotations: renderer fires an annotation event upstream → server stores it → next `DiagramData` push includes the annotation. The renderer never holds its own copy of annotations or board state. Stateless rendering keeps save/load trivial. + - The server includes the current `DiagramWorkspace` state in the `ObserverSnapshot`. The workspace is a list of `DiagramData` instances the player currently has access to. + - Four rendering modes (Network, Flow, Table, Spatial). Two layout strategies for Network (free and position-constrained). A thin interaction event layer. That is the entire scope of the rendering infrastructure. +- **Open design questions:** + 1. **Data contract details:** What node and edge types must the v0.1 contract support? Minimum viable: typed nodes + typed edges + optional metadata (label, confidence, timestamp). + 2. **Rendering vocabulary:** What visual primitives does the renderer expose — node shapes, edge styles, grouping/clustering, highlight states? What is explicitly out of scope for v0.1? + 3. **Lifecycle API:** What interface does an upstream system use to create, update, and close a board? Is this an ECS component, an IPC message, a client-side data structure, or some combination? + 4. **Player agency:** Is the board a read-only surface (upstream system writes, player reads) or can the player annotate — add notes, draw edges, pin nodes? If player writes are allowed, who owns that state? (Sprint 22 analysis: server owns annotation state; renderer is stateless.) + 5. **Insert integration:** How does the board surface within the insert UI — as a spoke, a workspace tab, a contextual overlay? How does the player navigate between multiple open boards? + 6. **v0.1 scope:** What is the minimum board implementation that validates the primitive — one upstream consumer, one node type, one edge type — without committing to a full vocabulary prematurely? +- **Context:** Q-052 §scaling note flagged "a complementary active system (case board, network map) the player reads rather than passively receives" as out of scope for the hint delivery question. This is that system. Lead direction (Sprint 22): the rendering infrastructure is agnostic to data source; what attaches to a board, what populates it, and what its lifecycle is are decisions owned by the upstream system, not the renderer. +- **Source:** Team Lead direction, Sprint 22 planning, 2026-02-28. +- **Assigned to:** Gestalt, Paula +- **Cross-reference:** Q-053 (board design philosophy — the "what" and "why"), Q-052 (storyteller hint delivery — boards noted as separate design problem), D-056/D-057 (insert diegetic conventions), D-023 (storyteller — one natural upstream consumer), D-024 (NPC axes — node content candidate) + +--- + +*9 questions (5 resolved, 1 partially resolved, 3 open). Last updated: 2026-02-28.* diff --git a/decisions/questions-scope.md b/decisions/questions-scope.md new file mode 100644 index 000000000..33859ece0 --- /dev/null +++ b/decisions/questions-scope.md @@ -0,0 +1,91 @@ +# Open Questions — Scope + +Game concept, prototype boundaries, production pipeline, and feature decisions. + +--- + +### Q-002: Scope of v0.1 playable prototype +- **Status:** Map spec resolved ([D-014](scope.md#d-014-v01-map-specification)). Remaining: mechanics, characters, interactions for minimum playable build. +- **Assigned to:** Full team + +### Q-004: One campaign spanning all eras or separate era scenarios? +- **Status:** Not yet discussed +- **Context:** Gore raised that Commonwealth Era and Void Era play very differently. Prototype focuses on pre-Starflyer War era. +- **Assigned to:** Gore, Miri to lead discussion + +### Q-005: Scale for prototype - locations, characters, factions +- **Status:** Partially scoped +- **Early signal:** Institute/Armstrong City hub, ~10-20 characters, Guardians + institutional + political factions +- **Assigned to:** Gestalt, Tyre, Miri + +### Q-007: Target platform(s) +- **Status:** Not yet discussed +- **Context:** Team Leader has Linux background (Fedora). Cross-platform considerations? +- **Assigned to:** Tyre + +### Q-008: Licensing / distribution model +- **Status:** Not yet discussed +- **Question:** Open source? Free? Commercial? This affects engine choice and asset decisions. +- **Assigned to:** Team Leader + +### Q-011: Character selection and playable characters +- **Status:** Not yet discussed +- **Question:** Which characters are playable in the prototype? How different are their starting positions? Can you play canon characters or only original ones? +- **Assigned to:** Miri, Paula + +### Q-027: Fast-travel system design +- **Status:** Open +- **Question:** How does inter-system travel work in production gameplay? The current hub teleport (Home key, #501) is scoped as Gauntlet-only dev tool. Production travel must be diegetic and respect asymmetric information. Proposed flow: player goes to local gate → warps to system gate → interacts with target menu → jumps to destination system gate. Key constraints: + 1. **Region gating:** fast-travel only available from safe or fast-travel-enabled regions. If you rented transport to reach a remote location (e.g. mountain colony), you must return the transport to civilization first — this can be a skip-travel interaction but must happen in-world. + 2. **Asymmetric information:** NPCs observe arrivals and departures. Travel choices leak information (who saw you leave, who sees you arrive, what transport was used). + 3. **Home key in production:** at most, Home could prompt "Do you want to fast-travel to the system hub?" if in a safe/enabled region — never instant teleport. + 4. **Transport types:** walking, rented vehicle, public transit, gate network — each with different information exposure profiles. +- **Context:** #501 implemented instant Home key teleport gated behind `gauntlet_mode`. Re-scoped to Gauntlet-only after design review. Production fast-travel needs separate design and implementation. +- **Assigned to:** Gestalt, Paula, Tyre +- **Source:** Sprint 10 PR review discussion (2026-02-19) + +### Q-032: Cultural ingredients menu +- **Status:** Open +- **Question:** Should world generation use a 6-category cultural ingredients menu (Heritage Roots, Settlement Motivation, Economic Function, Philosophical Alignment, Corporate/Faction Presence, Drift Stage) where each culture is composed by selecting from ingredient lists? The lead approved the "ingredients menu" model over fixed cultural taxonomies. Full specification needed: category definitions, ingredient lists per category, composition rules, absence-as-signal mechanics. +- **Assigned to:** Miri, Gestalt +- **Source:** Wiki Review Workshop R4, lead interview + +### Q-034: PC archetypes +- **Status:** Open +- **Question:** Should the full game support 8 fluid PC archetypes (Smuggler, Detective, Engineer, Diplomat, Medic, Scholar, Soldier, Merchant) with transition mechanics where archetype shifts during play based on player behavior? The lead approved 8 archetypes with fluid transitions as a game mechanic. v0.1 ships smuggler + detective only (D-027). Full archetype spec, transition triggers, and "vulnerable window" mechanics are undesigned. NOTE: The character-creation-game-setup workshop (Q-011) will address this — coordinate. +- **Assigned to:** Nigel, Gestalt +- **Source:** Wiki Review Workshop R4, lead interview + +### Q-035: Sacred/Profane/Middle Kingdom framework +- **Status:** Open +- **Question:** Should all game systems map to a Sacred/Profane/Middle Kingdom architectural framework? The lead approved this model where Sacred = what the system protects, Profane = what threatens it, Middle Kingdom = where the player navigates. The wiki-review workshop produced a full mapping table covering information, social, economic, spatial, temporal, and narrative systems. Needs formal specification and validation against current architecture. +- **Assigned to:** Gore, Gestalt +- **Source:** Wiki Review Workshop R4, lead interview + +### Q-036: District skeleton as generator output +- **Status:** Open +- **Question:** For the 300-world model, should the district skeleton (social sites, NPC slots, triangle templates, economic function, access topology) be the atomic output unit of the world generator? D-025 defines social sites as the atomic template unit for hand-authoring. The generator model reframes the district as a composed output from ingredient inputs. How does this interact with D-025? +- **Assigned to:** Tyre, Gestalt +- **Source:** Wiki Review Workshop R4 + +### Q-037: Generator development pipeline +- **Status:** Open +- **Question:** Should content production follow a 6-phase generator pipeline (Ingredient Authoring, Template Authoring, Generator Development, Validation Development, Generation + Review, Hand-Elevation)? The wiki-review workshop proposed this as the production model for 300 worlds. SI mapped a release path (v0.1 hand-authored, v0.2-0.5 template expansion, v0.6-0.10 generator development, pre-v1.0 validation). Needs scope assessment and sprint planning integration. +- **Assigned to:** SI, Tyre +- **Source:** Wiki Review Workshop R4 + +### Q-038: Authored content estimate at 300-world scale +- **Status:** Open +- **Question:** What is the irreducible authored content volume for 300 worlds? The wiki-review workshop estimated ~1,600-2,800 hours of hand-authoring for generator inputs (ingredient definitions, template specifications, validation rules, hand-elevation passes). How does this compare to the 20-district hand-authoring model it replaced? Is this estimate still valid given subsequent architectural decisions? +- **Assigned to:** Mellanie, SI +- **Source:** Wiki Review Workshop R4 + +### Q-039: Gate topology generation +- **Status:** Open +- **Question:** How should the world generator produce gate (wormhole) network topology for 300 worlds? The wiki-review workshop proposed: gate connectivity = Sacred (what connects), which worlds connect = Profane (what separates), accessible world count = Middle Kingdom (where the player navigates). Small-world network properties, hub-and-spoke vs mesh topology, and Sacred/Profane constraints on gate placement are all unresolved. D-012 covers chunk-based map architecture but predates the 300-world model. +- **Assigned to:** Tyre, Nigel +- **Source:** Wiki Review Workshop R4 + +--- + +*14 questions (0 resolved, 1 partially resolved, 13 open). Last updated: 2026-02-28.* diff --git a/decisions/questions.md b/decisions/questions.md index f428af0b0..952f8ea28 100644 --- a/decisions/questions.md +++ b/decisions/questions.md @@ -1,422 +1,36 @@ # Open Questions -Tracked questions awaiting discussion or resolution. +Tracked questions awaiting discussion or resolution. Split by domain, mirroring the D-record structure. ---- +## Domain Files -### Q-001: Game engine selection -- **Status:** Resolved → [D-020](architecture.md#d-020-engine-and-architecture-selection--godot-client--rust-simulation-via-subprocessipc) +| File | Domain | Questions | +|------|--------|-----------| +| [questions-architecture.md](questions-architecture.md) | Technical foundation | Q-001, Q-006, Q-009, Q-018, Q-019, Q-020, Q-021, Q-022, Q-023, Q-029, Q-030, Q-046 | +| [questions-perception.md](questions-perception.md) | Player observation | Q-003, Q-014, Q-016, Q-024, Q-025, Q-026, Q-051, Q-053, Q-054 | +| [questions-content.md](questions-content.md) | Narrative, NPCs, setting | Q-010, Q-012, Q-013, Q-015, Q-017, Q-028, Q-031, Q-033, Q-040, Q-041, Q-042, Q-043, Q-044, Q-045, Q-047, Q-048, Q-049, Q-050, Q-052 | +| [questions-scope.md](questions-scope.md) | Game concept, prototype | Q-002, Q-004, Q-005, Q-007, Q-008, Q-011, Q-027, Q-032, Q-034, Q-035, Q-036, Q-037, Q-038, Q-039 | -### Q-002: Scope of v0.1 playable prototype -- **Status:** Map spec resolved ([D-014](scope.md#d-014-v01-map-specification)). Remaining: mechanics, characters, interactions for minimum playable build. -- **Assigned to:** Full team +## Status Summary -### Q-003: Art direction / presentation style -- **Status:** Further resolved for v0.1 via Content Gap Analysis Workshop. Araminta's v0.1 Visual Grammar proposal covers: entity color palette (D-033), zone-specific color palettes (3 zones with hex values), fog rendering (4 states), monologue presentation spec, insert dual-character variants. Long-term art direction beyond v0.1 remains open. -- **Remaining:** Long-term art direction, sprite replacement timeline, full visual identity. -- **Assigned to:** Araminta (lead) +| Domain | Total | Resolved | Partial | Open | +|--------|-------|----------|---------|------| +| Architecture | 12 | 6 | 1 | 5 | +| Perception | 9 | 5 | 1 | 3 | +| Content | 19 | 5 | 1 | 13 | +| Scope | 14 | 0 | 1 | 13 | +| **Total** | **54** | **16** | **4** | **34** | -### Q-004: One campaign spanning all eras or separate era scenarios? -- **Status:** Not yet discussed -- **Context:** Gore raised that Commonwealth Era and Void Era play very differently. Prototype focuses on pre-Starflyer War era. -- **Assigned to:** Gore, Miri to lead discussion +## Adding a Question -### Q-005: Scale for prototype - locations, characters, factions -- **Status:** Partially scoped -- **Early signal:** Institute/Armstrong City hub, ~10-20 characters, Guardians + institutional + political factions -- **Assigned to:** Gestalt, Tyre, Miri +1. Claim an ID: `tooling/db/decision claim Q questions "title"` +2. Edit the appropriate domain file (`questions-{domain}.md`) +3. Follow the existing format (`### Q-NNN: Title` heading) +4. Update the domain file footer count +5. Update this index: add the ID to the domain table row, update status summary -### Q-006: Multiplayer or single-player only? -- **Status:** Resolved → [D-009](architecture.md#d-009-multiplayer---design-for-it-build-single-player-first) +## Domain Guide -### Q-007: Target platform(s) -- **Status:** Not yet discussed -- **Context:** Team Leader has Linux background (Fedora). Cross-platform considerations? -- **Assigned to:** Tyre +When in doubt about where a question belongs: if it constrains **how we build**, it's architecture. If it defines **what the player observes or knows**, it's perception. If it defines **narrative, NPCs, dialogue, or setting**, it's content. If it defines **what we ship or how big it is**, it's scope. -### Q-008: Licensing / distribution model -- **Status:** Not yet discussed -- **Question:** Open source? Free? Commercial? This affects engine choice and asset decisions. -- **Assigned to:** Team Leader - -### Q-009: Time system -- **Status:** Resolved → [D-031](architecture.md#d-031-time-system--game-clock-and-day-phases) - -### Q-010: Storyteller AI design -- **Status:** Not yet discussed -- **Question:** How does the Rimworld-style storyteller work? What are the pacing rules? How much structural randomness vs dramatic randomness? -- **Assigned to:** Gestalt, Nigel - -### Q-011: Character selection and playable characters -- **Status:** Not yet discussed -- **Question:** Which characters are playable in the prototype? How different are their starting positions? Can you play canon characters or only original ones? -- **Assigned to:** Miri, Paula - -### Q-012: Generation expansion method for dialogue -- **Status:** Open -- **Question:** How does the 4x generation expansion pass work? LLM-based, template-based, or rule-based? Affects how base lines are authored — LLM needs style-strong anchors; rules need substitution patterns. -- **Assigned to:** Gestalt, Mellanie -- **Source:** Content Gap Analysis Workshop (Mellanie R2) - -### Q-013: Line previewer temporal progression -- **Status:** Open -- **Question:** How does the line previewer (#193) handle THE FRIEND's multi-visit contradiction arc? Needs sequence mode to simulate interaction progression over multiple encounters. -- **Assigned to:** Gestalt, Dudley -- **Source:** Content Gap Analysis Workshop (Mellanie R2) - -### Q-014: Audio timing with monologue chime -- **Status:** Resolved → [D-067](perception.md#d-067-recognition-chime-fires-at-onset-of-cognitive-delay) -- **Resolution:** Chime fires at ONSET of cognitive delay, not completion. 300-400ms duration, overlapping delay start. Chime is "unresolved" — opens a question, doesn't answer one. Sequence: hear/sense → chime plays → 0.6s delay begins → monologue text during delay → blob transitions to D-033 color → recognition complete. -- **Date resolved:** 2026-02-16 - -### Q-015: Generation expansion for THE FRIEND content -- **Status:** Open -- **Question:** Does the 4x generation expansion apply to THE FRIEND's custom lines, or are all ~70-100 lines per FRIEND hand-authored? Recommendation: no expansion on FRIEND lines — risk of flattening hand-crafted voice. -- **Assigned to:** Mellanie, Gestalt -- **Source:** Content Gap Analysis Workshop (Ozzie R2, Gestalt R2) - -### Q-016: Knowledge hierarchy for monologue prerequisites -- **Status:** Resolved → [D-041](architecture.md#d-041-knowledge-graph-data-model) -- **Resolution:** 4-level hierarchy: `Suspects < KnowsOf < KnowsDetails < Direct`. Suspects = "something's off", gates initial investigation and vague monologue. KnowsOf = "X is involved in Y", gates topic-specific dialogue and peer-tier access. KnowsDetails = actionable detail, gates confrontation and secret-tier dialogue. Direct = currently in LOS, provides live position data. Maps to D-028 access tiers and D-035 prerequisite tags. -- **Date resolved:** 2026-02-11 -- **Source:** Knowledge Graph & Information Boundaries Workshop - -### Q-017: Triangle pressure threshold -- **Status:** Open -- **Question:** Triangles need a numeric pressure value that increases based on events. When it crosses a threshold, `confrontation` situation activates. What events increase pressure? What's the threshold? -- **Assigned to:** Gestalt, Paula -- **Source:** Content Gap Analysis Workshop (Gestalt R2) - -### Q-018: Shadowcasting algorithm selection -- **Status:** Resolved → [D-035](perception.md#d-035-symmetric-shadowcasting-albert-ford-selected-for-los-computation) -- **Question:** Which line-of-sight algorithm should be used? Symmetric shadowcasting (Albert Ford) vs recursive shadowcasting. Both are proven but differ in symmetry properties (symmetric: if A sees B, then B sees A) and implementation complexity. Requires benchmarking at 150x150 map scale with 30 entities to validate performance within 100ms tick budget. -- **Context:** D-011 mandates LOS shadowcasting for fog of perception. Architecture review identified this as unspecified (audit section 2.2). Critical for Sprint 2 perception pipeline. -- **Assigned to:** Tyre, Dudley -- **Source:** Architecture Review Audit 2026-02-11 - -### Q-019: Entity ID stability strategy -- **Status:** Partially resolved → [D-041](architecture.md#d-041-knowledge-graph-data-model) -- **Resolution:** Server-side: `StableEntityId` component + `EntityRegistry` resource provides bidirectional `StableId(u64) <-> Entity` mapping. StableId assigned once at entity spawn, never changes, persists across save/load. Knowledge graphs reference StableId, not bevy Entity. Client-side mapping (Godot StableId -> scene node lifecycle) remains open. -- **Remaining:** Client-side entity lifecycle management, scene node mapping strategy. -- **Date partially resolved:** 2026-02-11 -- **Assigned to:** Tyre, Dudley (client-side portion) -- **Source:** Knowledge Graph & Information Boundaries Workshop - -### Q-020: Multi-entity collision resolution -- **Status:** Open -- **Question:** When two NPCs attempt to move to the same tile on the same tick, what is the resolution policy? Options: first-write-wins (deterministic with system ordering), both fail (conservative), priority-based (e.g., player > NPC, Active tier > Background tier). -- **Context:** D-012 defines tile collision. WalkabilityMap exists (server/src/simulation/movement.rs) but handles single-entity validation. Architecture review identified multi-entity collision as unspecified. -- **Assigned to:** Gestalt, Dudley -- **Source:** Architecture Review Audit 2026-02-11 - -### Q-021: Tick budget overflow policy -- **Status:** Open -- **Question:** When a simulation tick exceeds the 100ms budget, what happens? Options: (1) slow down real-time and preserve determinism (tick completes fully before next), (2) skip ticks and break determinism, (3) cap work per tick and defer to next tick. Must align with D-010 principle 4 (deterministic simulation). -- **Context:** D-026 defines 100ms tick budget for Active tier at 10 tps. Architecture review consensus recommendation proposes "slow real-time, don't skip ticks." Needs formal decision. -- **Assigned to:** Tyre, Dudley -- **Source:** Architecture Review Audit 2026-02-11 - -### Q-022: NPC pathfinding cache eviction -- **Status:** Open -- **Question:** With 80 Active-tier NPCs each caching ~3 pathfinding routes, the cache holds ~240 paths. What is the eviction policy? LRU? Time-based expiration? Fixed size per NPC? How are paths invalidated when walkability changes (doors lock, areas become restricted)? -- **Context:** Architecture review identified pathfinding as MEDIUM gap (audit section 2.2). Cache management needs specification regardless of algorithm choice. -- **Assigned to:** Tyre, Dudley -- **Source:** Architecture Review Audit 2026-02-11 - -### Q-023: Debug visualization scope -- **Status:** Open -- **Question:** What information should the debug overlay display? Candidates: LOS rays, pathfinding waypoints, vision cones, information boundary tags (who knows what), tick timing breakdown, spatial partition grid cells. Dev-only tool, or accessible for mod development? -- **Context:** Architecture review (Troblum) identifies debug visualization as missing operational infrastructure. Needed for debugging perception system, information boundaries, and performance issues. -- **Assigned to:** Tyre, Stig -- **Source:** Architecture Review Audit 2026-02-11 - -### Q-024: Gossip propagation timing -- **Status:** Resolved → [D-080](perception.md#d-080-npc-to-npc-knowledge-propagation) -- **Resolution:** Knowledge transfer occurs via a separate `transfer_npc_knowledge` Bevy system running `after(run_npc_conversations)`. Transfer fires once per conversation at conversation start (immediate during conversation, not queued). Rate: 1–3 facts drawn by recency. Trust-tier gated. See D-080 for full specification. -- **Closed by:** Knowledge Flow & NPC Information Boundaries Workshop — unanimous. 2026-02-24. -- **Source:** Knowledge Graph & Information Boundaries Workshop (Gestalt Round 1); resolved in Knowledge Flow & NPC Information Boundaries Workshop Round 2. - -### Q-025: Knowledge graph cap and eviction strategy -- **Status:** Resolved — no cap or eviction needed for v0.1/v0.2. Re-evaluation trigger: Active NPC count > 200 OR KG memory exceeds 50 MB. -- **Question:** At what point does an NPC's knowledge graph need entry eviction? What is the eviction policy? -- **Resolution (2026-02-24, confirmed by Knowledge Flow workshop):** Current analysis: ~14 KB per Active NPC KG (50 entities + 20 facts, D-041 budget). 80 Active NPCs = ~1.1 MB. 2,000 Background NPCs at 10 entries = ~5 MB. Total ~6 MB. With gossip propagation shipping in Sprint 17 (D-080, 1–3 facts per conversation): estimated ~12 MB peak at current NPC counts. Neither re-evaluation condition expected before v0.3. The existing decay system (`decay_knowledge` in `knowledge/events.rs`) downgrades confidence and marks entries Stale but does not remove them — correct behavior (preserves "I used to know X" for narrative). If eviction becomes necessary, simplest policy: on each decay pass, if entities.len() > MAX_ENTITIES, remove Stale entries with lowest last_updated_tick. BTreeMap makes this O(N). -- **Closed by:** Knowledge Flow & NPC Information Boundaries Workshop — Tyre, Gestalt, Dudley confirmed; Paula non-objection noted. 2026-02-24. -- **Source:** Knowledge Graph & Information Boundaries Workshop (Dudley Round 1, section 8.3). Architecture audit 2026-02-23. Workshop confirmation 2026-02-24. - -### Q-026: Contradiction detection algorithm -- **Status:** Resolved → [D-083](perception.md#d-083-contradiction-detection-pipeline) -- **Resolution:** Event-driven detection at KG write time in `observe_entity()`, using `ContradictionClaim` struct. Location contradiction is automatic (Sprint 17): position comparison + time window (CONTRADICTION_WINDOW_TICKS = 600). Attribute and fact contradiction are content-authored (Sprint 18). Both ToldBy and DirectObservation entries receive Contradicted state (epistemic neutrality). `ContradictionDetected` event → monologue with resolved display names → relationship shift → AnomalyMarker via existing pipeline. -- **Closed by:** Knowledge Flow & NPC Information Boundaries Workshop — unanimous on architecture. 2026-02-24. -- **Source:** Knowledge Graph & Information Boundaries Workshop (Gestalt/Paula Round 1); resolved in Knowledge Flow & NPC Information Boundaries Workshop Round 2. - -### Q-027: Fast-travel system design -- **Status:** Open -- **Question:** How does inter-system travel work in production gameplay? The current hub teleport (Home key, #501) is scoped as Gauntlet-only dev tool. Production travel must be diegetic and respect asymmetric information. Proposed flow: player goes to local gate → warps to system gate → interacts with target menu → jumps to destination system gate. Key constraints: - 1. **Region gating:** fast-travel only available from safe or fast-travel-enabled regions. If you rented transport to reach a remote location (e.g. mountain colony), you must return the transport to civilization first — this can be a skip-travel interaction but must happen in-world. - 2. **Asymmetric information:** NPCs observe arrivals and departures. Travel choices leak information (who saw you leave, who sees you arrive, what transport was used). - 3. **Home key in production:** at most, Home could prompt "Do you want to fast-travel to the system hub?" if in a safe/enabled region — never instant teleport. - 4. **Transport types:** walking, rented vehicle, public transit, gate network — each with different information exposure profiles. -- **Context:** #501 implemented instant Home key teleport gated behind `gauntlet_mode`. Re-scoped to Gauntlet-only after design review. Production fast-travel needs separate design and implementation. -- **Assigned to:** Gestalt, Paula, Tyre -- **Source:** Sprint 10 PR review discussion (2026-02-19) - -### Q-028: Collision-resistant line IDs for auto-generated NPCs -- **Status:** Resolved → [D-084](content.md#d-084-dual-namespace-line-id-scheme--role-pool--instance-override) -- **Resolution:** The collision problem is mostly already solved by the role-pool architecture: `dock-worker_d_###` lines are shared content for all instances of the role, not per-instance IDs. A true collision (two distinct authored lines sharing the same ID) cannot occur with one file per role. For the edge case of authored instance-specific content, a role-slug + zero-padded generation counter suffix produces `dock-worker-07_d_001`. Counter is seeded-deterministic. No schema change, no migration. Hand-authored NPCs unchanged. -- **Closed by:** Gestalt (Sprint 18, #544). 2026-02-25. -- **Ticket:** #544 -- **Assigned to:** Gestalt, Tyre -- **Source:** Sprint 16 PR #59 review discussion (2026-02-23) - -### Q-029: Save file format design -- **Status:** Open -- **Question:** What should the long-term save file format look like? Key considerations: - 1. **Versioning and migration:** How do saves survive across game versions? Schema evolution strategy (field additions, renames, removals). Should saves embed a version number and run migrations on load? - 2. **Compression:** Raw MessagePack vs compressed (zstd, lz4)? Tradeoff between save/load speed and file size. SaveStateV1 is already MessagePack — does that carry forward? - 3. **Integrity:** Checksums or signatures to detect corruption? CRC32 header? - 4. **Metadata header:** Should the file have a readable header (game version, save date, play time, character name) that the loading screen can read without deserializing the full save? - 5. **Determinism:** D-010 requires deterministic simulation. Can saves capture enough state to resume deterministically, or is approximate resume acceptable? - 6. **Modding:** Should the format be documented for mod authors? Does it need extension points? - 7. **Cloud sync:** Any considerations for Steam Cloud or similar? File size limits? -- **Context:** Sprint 19 implements a quick-and-dirty save format (D-085 per-game directories, MessagePack serialization from SaveStateV1). This question tracks the thorough design pass for production quality. -- **Assigned to:** Tyre, Dudley -- **Source:** Team Leader directive (Sprint 19 planning) - -### Q-030: Seed configuration schema -- **Status:** Open -- **Question:** What artifact records all randomizer decisions at game start? The wiki-review workshop proposed a `seed-state.yaml` capturing: world seed, character selection, pool draws (Tier 1 modules, FRIEND selection, contraband variant), template assignments, NPC trait rolls, triangle configurations, and entanglement pattern. Ticket #394 (seed configuration schema design) exists but the design is open. -- **Assigned to:** Tyre, Gestalt -- **Source:** Wiki Review Workshop + v0.1 Content Scoping Workshop - -### Q-031: Combined content style guide -- **Status:** Open -- **Question:** Should the project have a single combined content style guide merging Paula's tier templates, Mellanie's voice conventions, Gestalt's mechanical constraints, and Miri's regional guide? The wiki-review workshop proposed this as a deliverable but it was never authored. What format, who owns it, and does it block content authoring? -- **Assigned to:** Mellanie, Paula -- **Source:** Wiki Review Workshop R2 - -### Q-032: Cultural ingredients menu -- **Status:** Open -- **Question:** Should world generation use a 6-category cultural ingredients menu (Heritage Roots, Settlement Motivation, Economic Function, Philosophical Alignment, Corporate/Faction Presence, Drift Stage) where each culture is composed by selecting from ingredient lists? The lead approved the "ingredients menu" model over fixed cultural taxonomies. Full specification needed: category definitions, ingredient lists per category, composition rules, absence-as-signal mechanics. -- **Assigned to:** Miri, Gestalt -- **Source:** Wiki Review Workshop R4, lead interview - -### Q-033: Three-system NPC architecture -- **Status:** Open -- **Question:** Should NPCs be formally composed from 9 thematic patterns (FRIEND, MIRROR, ANCHOR, GHOST, CATALYST, THRESHOLD, REMNANT, SYSTEM, NOBODY) x 6 functional motivations (HANDLER, WITNESS, TURNCOAT, CIVILIAN, OPERATOR, SKEPTIC)? D-024 defines 10 axes + combat but predates this refined system. The wiki-review workshop produced a full composition matrix with drama ratings and forbidden combinations. Does this supersede D-024 or extend it? -- **Assigned to:** Gestalt, Paula -- **Source:** Wiki Review Workshop R4 - -### Q-034: PC archetypes -- **Status:** Open -- **Question:** Should the full game support 8 fluid PC archetypes (Smuggler, Detective, Engineer, Diplomat, Medic, Scholar, Soldier, Merchant) with transition mechanics where archetype shifts during play based on player behavior? The lead approved 8 archetypes with fluid transitions as a game mechanic. v0.1 ships smuggler + detective only (D-027). Full archetype spec, transition triggers, and "vulnerable window" mechanics are undesigned. NOTE: The character-creation-game-setup workshop (Q-011) will address this — coordinate. -- **Assigned to:** Nigel, Gestalt -- **Source:** Wiki Review Workshop R4, lead interview - -### Q-035: Sacred/Profane/Middle Kingdom framework -- **Status:** Open -- **Question:** Should all game systems map to a Sacred/Profane/Middle Kingdom architectural framework? The lead approved this model where Sacred = what the system protects, Profane = what threatens it, Middle Kingdom = where the player navigates. The wiki-review workshop produced a full mapping table covering information, social, economic, spatial, temporal, and narrative systems. Needs formal specification and validation against current architecture. -- **Assigned to:** Gore, Gestalt -- **Source:** Wiki Review Workshop R4, lead interview - -### Q-036: District skeleton as generator output -- **Status:** Open -- **Question:** For the 300-world model, should the district skeleton (social sites, NPC slots, triangle templates, economic function, access topology) be the atomic output unit of the world generator? D-025 defines social sites as the atomic template unit for hand-authoring. The generator model reframes the district as a composed output from ingredient inputs. How does this interact with D-025? -- **Assigned to:** Tyre, Gestalt -- **Source:** Wiki Review Workshop R4 - -### Q-037: Generator development pipeline -- **Status:** Open -- **Question:** Should content production follow a 6-phase generator pipeline (Ingredient Authoring, Template Authoring, Generator Development, Validation Development, Generation + Review, Hand-Elevation)? The wiki-review workshop proposed this as the production model for 300 worlds. SI mapped a release path (v0.1 hand-authored, v0.2-0.5 template expansion, v0.6-0.10 generator development, pre-v1.0 validation). Needs scope assessment and sprint planning integration. -- **Assigned to:** SI, Tyre -- **Source:** Wiki Review Workshop R4 - -### Q-038: Authored content estimate at 300-world scale -- **Status:** Open -- **Question:** What is the irreducible authored content volume for 300 worlds? The wiki-review workshop estimated ~1,600-2,800 hours of hand-authoring for generator inputs (ingredient definitions, template specifications, validation rules, hand-elevation passes). How does this compare to the 20-district hand-authoring model it replaced? Is this estimate still valid given subsequent architectural decisions? -- **Assigned to:** Mellanie, SI -- **Source:** Wiki Review Workshop R4 - -### Q-039: Gate topology generation -- **Status:** Open -- **Question:** How should the world generator produce gate (wormhole) network topology for 300 worlds? The wiki-review workshop proposed: gate connectivity = Sacred (what connects), which worlds connect = Profane (what separates), accessible world count = Middle Kingdom (where the player navigates). Small-world network properties, hub-and-spoke vs mesh topology, and Sacred/Profane constraints on gate placement are all unresolved. D-012 covers chunk-based map architecture but predates the 300-world model. -- **Assigned to:** Tyre, Nigel -- **Source:** Wiki Review Workshop R4 - -### Q-040: Gate dual-use topology — freight and commuter on shared span gate infrastructure -- **Status:** Resolved → D-093 (gate cluster zone spec), D-095 (span gate dual-use windows) -- **Question:** System span gates serve both freight and commuter traffic (one gate per system). How does this work physically? Is it one gate aperture with scheduling (freight window vs. passenger window), or parallel lanes (separate apertures for freight and passenger flows)? What does the gate facility look like from the inside — a single large bay or divided infrastructure? -- **Layout implication:** Affects the gate cluster spatial design in the Transit District — the gate cluster must accommodate both freight staging and passenger throughflow, possibly at different times of day. -- **Assigned to:** Miri -- **Source:** Station District Layout Workshop (#153), Round 2. Surfaced by lead correction to Miri's S-02 (commuter transit ≠ second external gate). -- **Cross-reference:** D-036 (Sova setting), Q-036 (district skeleton as generator output) - -### Q-041: Interstellar travel mechanics — horizon stations and gate architecture -- **Status:** Resolved → D-095 (horizon stations: alien-built, 4–8 apertures, Oort-cloud, "The Ring"; sequential hop travel) -- **Question:** A system needs MORE than one horizon gate for multi-hop connectivity (one gate allows only 1:1 connections). Lead proposal (Round 3): **Horizon stations** — orbital installations at Oort-cloud distance, partially or wholly understood ancient alien technology, self-maintaining (Mass Effect relay/Citadel analog). Each horizon station holds a FIXED number of active and inactive horizon gates. Some systems may only have one hop to an orbital customs station with no direct planet-side span gate access. Remaining questions: How many gates per horizon station? What determines which gates are active vs. inactive? Is the travel instantaneous or traversal-based? What is "The Ring" (the orbital horizon station) like as a physical space? -- **Assigned to:** Miri -- **Source:** Station District Layout Workshop (#153), Round 2. Lead correction in Round 3: single-gate-per-system model insufficient for multi-hop travel; horizon station model proposed. -- **Cross-reference:** D-036 (Sova setting), Q-039 (gate topology generation), Q-040 (gate dual-use topology) - -### Q-042: Intra-system transport networks — passenger vs. freight, vehicles and modes -- **Status:** Partially resolved → D-095 (span gates at star/planetary level; horizon stations at Oort distance). Intra-system hab-to-hab transit remains open. -- **Question:** How do people and goods move within a star system (between orbital stations, planetary surfaces, and other in-system facilities)? Are there two separate networks (passenger transport and freight transport) or one shared network? What are the vehicle types and transit modes? How does intra-system transit interact with the span gate at the system's hub station? -- **Assigned to:** Miri -- **Source:** Station District Layout Workshop (#153), Round 2. Flagged by lead as transport lore requiring formal tracking. -- **Cross-reference:** D-036 (Sova setting), Q-043 (station internal transit) - -### Q-043: Station internal transit — intra-station transport system between districts -- **Status:** Resolved → D-095 (The Loop: 6-district tram, 4-minute Residential Core → Transit District; transit platform is bar-side encounter node) -- **Question:** What is the intra-station transport system on Station Sova? How do workers commute between districts (e.g., Residential Core → Transit District)? Is it a train, tram, shuttle, or pressurised corridor? What is the travel time and frequency? Where does the transit stop sit within the Transit District — gate-cluster-adjacent (workers arrive near freight operations) or bar-side-adjacent (workers arrive near their social space)? -- **Layout implication for #153:** The Transit District must include an internal transit stop. Its position within the district affects NPC traffic patterns and the district entry topology. This is the active T-03b question for Round 2/3 of the Station District Layout Workshop. -- **Assigned to:** Miri -- **Source:** Station District Layout Workshop (#153), Round 2. Arose from lead correction: commuter transit = internal station transit, not a second external gate. -- **Cross-reference:** D-036 (Sova setting), Q-042 (intra-system transport networks), S-02 revision - -### Q-044: Gate-train integration — do transport vehicles use gates directly or transfer on each side -- **Status:** Resolved → D-093/D-095 (gates are pedestrian/cargo-only; passengers transfer via gate concourse → transition corridor → transit platform; no direct gate-to-tram connection) -- **Question:** If trains or shuttles are the intra-system or intra-station transit mode, do they use the span gate directly (a train enters the gate and exits at the destination, carriages and all)? Or are the gates pedestrian/cargo-only, requiring passengers and freight to transfer to separate transport on each side? What does this imply for gate terminal design — does it need platforms, or just processing space? -- **Assigned to:** Miri -- **Source:** Station District Layout Workshop (#153), Round 2. Flagged by lead as transport lore requiring formal tracking. -- **Cross-reference:** Q-040 (gate dual-use topology), Q-043 (station internal transit) - ---- - -### Q-045: Axis 11 — Network Footprint NPC tag -- **Status:** Open -- **Priority:** High -- **Question:** Should the NPC model (D-024, 10 axes) gain an 11th axis: `network_footprint: Option` for NPCs who are locally insignificant in appearance but carry network-significant information or are relevant to external actors? Default `None` for procedural NPCs. Explicitly set for authored scenario NPCs. This would enable the storyteller to identify locally-invisible but network-critical nodes without breaking the NPC's mundane character. -- **Context:** Raised during Generator Architecture Workshop (#562). The Ysabel Vorn litmus test (4.5/5 playstyle hooks, Backwater/Moderate setting) demonstrated that locally-insignificant NPCs can be key network nodes. Without this field, the generator has no mechanism to flag them to the storyteller. -- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §NPC Model. -- **Assigned to:** Miri - -### Q-046: Departure schedule model — departure windows as generator output for docked vessels -- **Status:** Resolved → D-108 (MobileChunk Specification) -- **Resolution:** `scheduled_departure: Option` in `Docked` state is mandatory generator output. Vessels without departure schedules are an error state. The `Docked` struct must include `docked_since: SimTick` and `scheduled_departure: Option` — these fields must be added at implementation time (absent from Tyre's Round 4 canonical struct). -- **Date resolved:** 2026-02-27 -- **Source:** Generator Architecture Workshop (#562) -- **Assigned to:** Tyre + Miri - -### Q-047: Mobile environment social arc — structural representation of journey timeline -- **Status:** Open -- **Priority:** Medium -- **Question:** How is the social arc of a mobile environment journey (BoundedLinear / BoundedMobile) represented structurally? The journey has a beginning (boarding, strangers), middle (established dynamic), and end (departure, relationship crystallized). What game structures capture this timeline and enable the storyteller to intervene? Does `TransitSocialModifier` need a journey-phase field? -- **Context:** Ozzie's player experience requirement from Generator Architecture Workshop (#562): "the journey must have a social arc — not just social presence." The stage+cast framing is correct; the formal structural representation is unspecified. -- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §Open Questions. -- **Assigned to:** Miri + Gestalt - -### Q-048: DramaDensity enum naming — 3-level vs 5-level -- **Status:** Open -- **Priority:** Low -- **Question:** The Round 4 struct uses `Quiescent / Active / Intense` (3 levels). Round 3 proposed `Zero / Low / Medium / High / Flashpoint` (5 levels). Which should be canonical? Nigel's position: `Flashpoint` should be preserved as a distinct peak value — it is the storyteller's maximum-pressure instrument and should not collapse into `Intense`. If 3 levels are chosen for implementation simplicity, `Flashpoint` should still be the distinct peak name, not `Intense`. -- **Context:** ComplexityTier → DramaDensity ceiling (established): Full → any intensity; Moderate → Active max; Minimal → Quiescent max; Empty → Zero only. Naming must be consistent with these ceiling values. -- **Source:** Generator Architecture Workshop (#562), Rounds 3–4. `docs/workshops/generator-architecture/workshop-outcomes.md` §Open Questions. -- **Assigned to:** Tyre + Gestalt - -### Q-049: ObjectTag vocabulary co-maintenance — Miri and Araminta shared dependency -- **Status:** Open -- **Priority:** Medium -- **Question:** The `ObjectTag` vocabulary must be co-maintained between Miri's `HeritageGrammarOverlay` (cultural grammar, Rust struct) and Araminta's asset categorization (visual expression, TOML files). What is the governance model? Who owns the canonical tag list? How are additions and deprecations coordinated? Does the vocabulary live in the Rust struct definition or in a shared data file? -- **Context:** If the vocabulary diverges, the generator will reference tags that don't exist in asset categories, or assets will be authored that the grammar never references. This is a silent correctness failure. -- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §D-READY-9. -- **Assigned to:** Miri + Araminta - -### Q-050: Assassination difficulty synthesis — formal spec combining stored baseline with on-demand computation -- **Status:** Open -- **Priority:** Medium -- **Question:** Formal specification needed for the synthesis combining stored cultural baseline (`DerivedDistrictAnalysis` on Phase 1 skeleton) with on-demand runtime computation for player-facing assessment. Key constraint from Miri: **on-demand computation is display-only** — all game logic (tactical triangle instantiation, guarantee audit) uses the Phase 1 `DerivedDistrictAnalysis` value. The on-demand computation is subordinate to the stored baseline, not a replacement. -- **Context:** Minor tension between Gestalt's "computed entirely on demand" position and Miri's "stored cultural baseline" position. Synthesis accepted by both participants in Generator Architecture Workshop (#562); formal spec needed for implementation. -- **Source:** Generator Architecture Workshop (#562), Round 4. `docs/workshops/generator-architecture/workshop-outcomes.md` §Open Questions. -- **Assigned to:** Gestalt + Miri - -### Q-051: Speech bubble indicator over speaking NPCs -- **Status:** Open -- **Priority:** Low -- **Question:** Add a generic speech bubble icon above the head of any NPC that is currently speaking in a conversation. Consider reusing the per-character color coding from the dialogue log so the player can easily map speech bubbles to dialogue entries. -- **Context:** When multiple NPCs are nearby and the dialogue log is scrolling, it can be hard to tell who is speaking. A floating speech bubble icon (not the text itself — just the indicator) over the speaker's sprite would anchor dialogue to world position. Color-coding to match the dialogue log's per-character colors reinforces the mapping. -- **Assigned to:** Stig + Araminta - -### Q-052: Storyteller hint delivery — parallel diegetic channels when player does not act -- **Status:** Open (Sprint 22 analysis complete, awaiting implementation scoping) -- **Priority:** High -- **Question:** When a TriangleActivated event fires and the player does not investigate, what mechanisms create conditions for discovery? How do these scale from v0.1 (1-2 triangles) to the full game (300 worlds, 10+ simultaneous triangles, 8 archetypes)? -- **Core design principle:** "The storyteller is not delivering messages — it is creating conditions under which the player's existing relationships, existing investments, and existing world naturally produce signal." Player inaction is a valid outcome, not an error state. Consequences happen; the world moves on. -- **Channel inventory (ranked by deniability — least nudge-like first):** - 1. **Behavioral tell escalation** — activated triangle NPCs exhibit more pronounced tells (D-024 axis 9). Always active, proximity-gated. Feels like the world being alive. Scales infinitely, zero authoring per triangle. - 2. **Environmental change** — something physically different at the triangle location (locked door, moved cargo, light on at wrong hour). Archetype-agnostic: engineer reads the system fault, diplomat reads the guard rotation, merchant reads the sealed bay. Infinite scale, zero authoring per triangle. - 3. **Ambient sound cue** — audible change in the triangle zone (hushed conversation, footsteps at unusual time, a door that was open now shut). Uses D-018 three-range system. Proximity-gated. - 4. **Overheard NPC conversation** — secondary NPCs gossip about the activated NPC's changed behavior. Fires when two NPCs share a scene in a social site. Scales with the social simulation, not with authoring. Constraint: the NPC speaks from their own concerns ("He owes me for last week's haul and now he's not answering"), never from narrative convenience ("I think something is wrong with Kael"). - 5. **Unprompted NPC remark** — a non-job-giver NPC proactively comments when the player approaches. Uses D-028 Layer 4 unprompted disclosure with `situation: [triangle_activated]`. - 6. **FRIEND message** — the FRIEND NPC (D-034) reaches out. Structurally unique: when the FRIEND IS the triangle anchor (smuggler/Kael), the message is simultaneously the nudge and the tell — its timing, phrasing, and whether it sounds normal are the investigative data. Reserve for the triangle the FRIEND is directly connected to; degrades on overuse (one FRIEND per character = hard limit). - 7. **Internal monologue** — player character's inner voice notices something. Proximity-gated to triangle NPCs exhibiting tells. Character-specific voice (D-032, D-090). - 8. **Job-giver app message** — institutional backstop of last resort. Fires only if no other channel has produced player engagement. One per session maximum, for the single highest-engagement triangle only. Job-giver per archetype: smuggler = handler ("Dock 7, pickup, ask for Kael"), detective = Commission superior ("Welfare check, dock-level, concern logged by port authority"), engineer = fault log, diplomat = peer request, merchant = market signal. Three sender types: named NPC (personal), institution (semi-personal), automated system (impersonal). -- **Delivery model — parallel channels, not linear funnel:** - - All channels activate on TriangleActivated. The player encounters whichever their playstyle naturally intersects first. - - Channels have capacity, not triangles: monologue holds 1 thread (highest engagement wins), gossip holds 2-3, tells are unlimited. Lower-engagement triangles naturally get quieter channels — no starvation. - - App message has a long fuse; only delivers if no other channel has been "hit" (storyteller detects player engagement via any channel). Prevents the pattern from being predictable across playthroughs. - - Diegetic test for all channels: could you explain the output without reference to the activated triangle? If yes, diegetic. If no, quest marker. -- **Scaling properties (v0.1 → full game):** - - Channel priority inverts at scale. v0.1: authored channels (monologue, job-giver) dominate. Full game: universal channels (environmental, overheard, tells) are the foundation because they scale with the simulation, not with authoring. - - Job-giver coherence breaks if overused — handler sending player to 3 activated locations in one session becomes transparent. Backstop for highest-engagement triangle only. - - Hint adaptation: storyteller tracks `PlayerHintEngagement` — how often the player engages after each channel tier. Extends fuses and reduces probabilities as player demonstrates skill. Hours 1-5: full hints. Hours 15+: player reads the world by behavioral tells alone. "Not harder combat — a quieter, more trusting world." Resets per new playthrough. - - ~15-20 hour meta-awareness cap: beyond that, the game likely needs a complementary active system (case board, network map) the player reads rather than passively receives. Separate design problem, out of scope here. -- **Signal pollution gating:** - - Monologue: only when player is within proximity of a triangle NPC exhibiting tells. - - Gossip: only when the player initiates conversation with a connected secondary NPC. Passive, not pushed. - - FRIEND message: only if the FRIEND has a plausible in-world reason to reach out at this moment (established relationship cadence). - - Job-giver: once per session, backstop only. - - Environmental/tells: always active, no gating needed (they ARE the world). -- **Implementation implications:** - - Storyteller needs a `ChannelSet` per activated triangle tracking which channels have fired and whether the player has engaged. - - Post-activation state machine: `Activated → [channels live] → Resolved (player engages) | Consequences (timeout) | Expired`. - - NPC behavioral state changes need to register as conversation topics for social-network propagation (simulation feature, not content feature). - - App message content uses D-028 tagged line pools with new `situation: [app_message]` tag and sender-type sub-tag. Rendered in neural insert UI as message thread, not monologue overlay. -- **Content pipeline:** - - Universal channels (environmental, overheard, tells): zero per-triangle authoring. Build once as simulation features. - - Authored channels (monologue, FRIEND, job-giver): per-character/per-archetype investment. Layer on top as richness. - - Job-giver treated as authored feature shipping archetype by archetype, not universal system shipping once. -- **Context:** Raised during Sprint 22 storyteller scoping (#162). Analysis by Gestalt (systems) and Paula (narrative) across two rounds. -- **Cross-reference:** D-023 (storyteller activation), D-016 (monologue system), D-018 (three-range hearing), D-024 (NPC axes — tell system), D-028 (dialogue architecture), D-032 (separate monologue pools), D-034 (THE FRIEND), D-090 (character voice), #162 (storyteller module activation) -- **Assigned to:** Gestalt, Paula - -### Q-053: Insert workspace boards — design philosophy and information architecture -- **Status:** Open (Sprint 22 analysis complete) -- **Priority:** High -- **Question:** How do boards function as the player's primary active information surface, and what design principles govern their behaviour across archetypes, game phases, and concurrent use? -- **Core design principle:** Boards are a **general-purpose communication layer** to the player, not a mechanic in themselves. The renderer is agnostic — it takes structured data and draws it. What creates a board, what populates it, and what its lifecycle is are decisions owned by the upstream system (quest, journal, navigation, business management, faction tracking, etc.), not the renderer. -- **Design principles established:** - 1. **Epistemology map, not truth map.** "The board maps the player's epistemology, not the game's truth." Nodes appear as the player encounters them. Connections are always the player's work. The board never reveals information the player hasn't acquired through gameplay. - 2. **Passive nodes, active edges.** Things appear automatically when observed/learned; relationships between them are the player's inference. This makes the board a thinking tool, not a checklist. - 3. **Multiple concurrent boards.** A character can be on an investigation while running a business while tracking a social network. Boards attach to whatever upstream system creates them — a quest, a business, a journal category, a transit network. The workspace presents them as tabs or equivalent navigation. - 4. **Archetype-specific readings.** Same diagram data, different professional questions. Detective reads evidence chains, smuggler reads trust networks, engineer reads system diagrams, diplomat reads faction leverage, merchant reads supply lines. The rendering primitive is identical; the upstream system determines what nodes and edges mean. - 5. **Cross-board convergence as discovery.** When the same node appears on multiple boards, that IS the discovery moment. Consistent visual identity (same icon, same colour) lets player recognition do the work — no automatic highlighting, no "this person appears on another board!" popup. The player connects the dots. - 6. **Monologue as diagram interaction surface.** When the player focuses a board node, the monologue system can fire character-specific commentary. "He was at both meetings" is monologue, not board UI. This connects the active information system (Q-053) to the passive hint system (Q-052). -- **Transit maps — core navigation mechanic:** - - Transit maps are boards whose upstream system is the navigation/transport layer, not the political geography layer. They respond to political geography (route closures, faction control) but their primary function is **how the player gets around**. - - Implementation: Network renderer with position-constrained layout mode (nodes pinned to world coordinates). Same rendering primitive as investigation boards (free layout mode), different layout constraint. - - Transit maps exist from day one as a live, simulation-fed surface — not a static reference image. -- **Scaling properties:** - - v0.1: one or two board types (investigation + transit map) validate the rendering primitive and workspace navigation. - - Full game: boards proliferate naturally as upstream systems ship — business dashboards, faction maps, crew manifests, engineering schematics, social network visualisations, reference material (field guides, legal codes). - - Board count is not a design problem — it's a UX problem (workspace navigation, tab management, search/filter). The primitive scales inherently. -- **Context:** Raised during Sprint 22 planning. Initial framing included d2 syntax as in-game format; lead directed that d2 remains a dev tool only and is not involved in the in-game system. Analysis by Gestalt (systems) and Paula (narrative) across three rounds with multiple lead corrections. -- **Cross-reference:** Q-054 (rendering primitive data contract — the technical "how"), Q-052 (storyteller hint delivery — boards as the complementary active system), D-056/D-057 (insert diegetic conventions) -- **Assigned to:** Gestalt, Paula - -### Q-054: Insert workspace board — rendering primitive and data contract -- **Status:** Open -- **Priority:** High -- **Question:** What is the board rendering primitive and its data contract? A board is a **general-purpose structured information surface** rendered inside the insert workspace. The renderer is agnostic to data source — it takes structured data and draws it. Upstream systems (quests, journal, navigation, faction tracking, reference material, business management, or anything with structured data worth visualizing) are responsible for creating boards, populating them, and managing their lifecycle. The renderer does not know or care why a board exists. Open questions: - 1. **Data contract:** What is the schema the renderer consumes? Minimum viable: typed nodes + typed edges + optional metadata (label, confidence, timestamp). What node and edge types must the v0.1 contract support? - 2. **Rendering vocabulary:** What visual primitives does the renderer expose — node shapes, edge styles, grouping/clustering, highlight states? What is explicitly out of scope for v0.1? - 3. **Lifecycle API:** What interface does an upstream system use to create, update, and close a board? Is this an ECS component, an IPC message, a client-side data structure, or some combination? - 4. **Player agency:** Is the board a read-only surface (upstream system writes, player reads) or can the player annotate — add notes, draw edges, pin nodes? If player writes are allowed, who owns that state? - 5. **Insert integration:** How does the board surface within the insert UI — as a spoke, a workspace tab, a contextual overlay? How does the player navigate between multiple open boards? - 6. **v0.1 scope:** What is the minimum board implementation that validates the primitive — one upstream consumer, one node type, one edge type — without committing to a full vocabulary prematurely? -- **Context:** Q-052 §scaling note flagged "a complementary active system (case board, network map) the player reads rather than passively receives" as out of scope for the hint delivery question. This is that system. Lead direction (Sprint 22): the rendering infrastructure is agnostic to data source; what attaches to a board, what populates it, and what its lifecycle is are decisions owned by the upstream system, not the renderer. -- **Source:** Team Lead direction, Sprint 22 planning, 2026-02-28. -- **Assigned to:** Gestalt, Paula -- **Cross-reference:** Q-053 (board design philosophy — the "what" and "why"), Q-052 (storyteller hint delivery — boards noted as separate design problem), D-056/D-057 (insert diegetic conventions), D-023 (storyteller — one natural upstream consumer), D-024 (NPC axes — node content candidate) - ---- - -*54 questions (12 resolved, 2 partially resolved, 40 open). Last updated: 2026-02-28 (Q-053 filed — board design philosophy; Q-054 revised — rendering primitive data contract)* +*54 questions. Last updated: 2026-02-28 (split from single file into domain files).*