jpmschweitzerandClaude Opus 4.8
f936e503da
Phase 1 of the pql migration. Moves the flat decisions/*.md layout into
governance/{decisions,questions,rejected}/<domain>.md — the tree pql's
`decisions sync` parses natively (record type from subdir, domain from
filename stem). Proven against pql 1.6.2: sync reports 357 records
(237 D / 108 Q / 12 R), 1057 refs, broken: 0; validate ok.
- 6 D-domain files -> governance/decisions/ (git renames)
- 5 questions-<domain>.md -> governance/questions/<domain>.md (prefix dropped)
- rejected.md split by domain -> governance/rejected/{architecture(R-001..010),
economics(R-011),perception(R-012)}.md
- decisions/README.md + questions.md index folded into governance/README.md;
pql's `decisions sync` now auto-maintains the record index appended below
the hand-written domain guidance (no more manual ID-list table upkeep).
- .pql/config.yaml: canonical vault config (tracked, not ignored).
Link rewrites are token-preserving: only the relative `foo.md` path portion
changes (e.g. `rejected.md#r-011` -> `../rejected/economics.md#r-011`); every
`[D-NNN]` bracket text and `#anchor` stays byte-identical, so pql's reference
extraction is unaffected. The one-shot transform is committed at
tooling/pql-migrate/restructure_decisions.py for provenance.
Codebase path references to decisions/ (CLAUDE.md, rules, skills, docs) are
updated in a follow-up commit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
105 lines
16 KiB
Markdown
105 lines
16 KiB
Markdown
# 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](../decisions/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](../decisions/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](../decisions/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](../decisions/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<PlayerAnnotation> }` 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.*
|