Skip to main content

Open Questions

Status: living document — questions are added by waves and closed by user decisions or ADRs. Closed questions are moved to the relevant ADR or design doc rather than deleted from here. Status terms follow pr-status-and-sync-policy.md.

Purpose​

This document collects open questions that waves surface but that have not yet been resolved by user decision, ADR, or implementation. When a question is resolved, the implementer removes it from here and records the resolution in the relevant ADR, design doc, or decision note. Questions that span multiple waves belong here rather than in wave briefs, so that the wave brief stays focused on the wave's edits and the unresolved-question backlog stays visible across waves.

A question in this doc is not a TODO comment. It is a decision the project is consciously deferring because the answer requires either user input, an architectural decision worth its own ADR, or implementation evidence that is not yet available.

Behavior Vocabulary​

Wave D formalized Routine Activity and Composite Activity as planning-layer sub-forms of activity in docs/design/behavior-vocabulary.md and in systems/objectives-clues-missions.md. The remaining behavior-vocabulary questions are:

  • Whether Routine Activity and Composite Activity need their own ADR formalizing their sub-form status, or whether the behavior-vocabulary update in Wave D is sufficient. Today these terms are documented in the design doc's allowlist; they are not separately ADR'd. A future ADR may be desirable if downstream docs (combat doc, queue doc) need to refer to a single normative source for the sub-form distinction.

  • Whether the planning vocabulary doc should carry a section explaining when to use routine activity vs composite activity vs bare activity in player-facing prose. Wave D's rewrite uses the two sub-forms but does not enumerate concrete guidance on which to pick when authors are unsure. The vocabulary is currently governed by tone and context only.

See also: pr-wave-roadmap.md § ADR-Routine for the pending ADR stub.

Combat Screen Vocabulary​

Wave D renamed action_ref to activity_ref in ux/combat-dungeon-screen.md. Open questions:

  • Whether activity_ref is the correct field name for the renamed action_ref field in the behavior-branch template shape, or whether a different name (such as decision_ref or behavior_ref) is more appropriate for a template field holding a "which activity to fire" reference. The combat doc is a proposal, not part of the current client contract; the field name will be finalized when the proposal is implemented.

  • Whether the combat doc's existing behavior_ref field naming (used elsewhere in the same proposal for branch-bearing behavior templates) should be reconciled with activity_ref in a single pass when the proposal moves to implementation.

Tag Taxonomy​

catalogs/tag-catalog.md lists 14 committed tags and 19 planned terrain-derived tags. Open questions:

  • Whether the planned terrain tags in gd-location-generation-contract.md need a unified registry doc beyond the tag catalog, or whether the current split (catalog enumerates committed + planned; design surface in systems/tags-and-classification.md) is sufficient.

  • When the terrain tags should be promoted from "planned" to committed Content. The promotion path is documented in the catalog, but the trigger condition (production generator readiness, specific generator features that need the tags) is not yet specified.

  • Whether the modifier-vs-structural-predicate split should be enforced syntactically (e.g., a separate valenar:modifier-tag/... namespace) or remain a convention. Today it is a convention.

See also: pr-wave-roadmap.md § ADR-Terrain-tags for the pending ADR stub.

State Axes​

systems/state-axes-and-thresholds.md documents three axes, each with TBD elements. Open questions:

  • Numeric intensity field for the Location knowledge axis: no committed enum yet; field name (surveyProgress or otherwise) is TBD; scale (0–100, 0–1, integer step count) is TBD.

  • Numeric intensity field for the Site state axis: RESOLVED by Wave R-2 (2026-05-10). Field name StateIntensity, type int, default 0. Bare integer per the unified convention established by R-1's KnowledgeIntensity. Lives on SiteData, hashed as H.StateIntensity, declared in Generated/Declarations.cs, and read/written through the Site branch of HostBridge. Tracks intensity on the State (progress ladder) axis, not on DiscoveryState. Numeric thresholds within each ladder label remain TBD per a future balance wave; wire projection (SiteSnapshot) is deferred to a future Server wave. See systems/state-axes-and-thresholds.md "Site State Axis" and pr-code-sync-audit.md.

  • Feature discovery intensity field: PARTIALLY RESOLVED by Wave R-3 (2026-05-10). Field foundation shipped: int DiscoveryIntensity on FeatureData, default 0, hashed as H.DiscoveryIntensity, declared in Generated/Declarations.cs, and read/written through the Feature branch of HostBridge. Bare integer per the unified convention established by R-1's KnowledgeIntensity and R-2's StateIntensity. Wire projection (FeatureSnapshot.discoveryIntensity) is deferred to a future Server wave, mirroring R-2's SiteSnapshot deferral. See systems/state-axes-and-thresholds.md "Feature Discovery Axis" and pr-code-sync-audit.md.

  • Feature discovery intensity thresholds (the 0–100 ranges per label): whether these become committed numeric thresholds or remain design-intent guidance. The authority doc explicitly defers these to a balance pass. Closing this requires a future balance-pass wave.

  • Whether a unified progress / intensity field convention should be established across all three axes before implementing them individually, so that the storage shape and the wire shape are consistent.

See also: pr-wave-roadmap.md § ADR-State-intensity for the pending ADR stub.

Feature Category vs Tag​

generation/feature-generation-contract.md defines Feature categories (NaturalResource, Water, Food, Forest, Mineral, etc.) separately from the tag vocabulary in Content/common/tags.secs. Open question:

  • Whether Feature categories should eventually be expressed as committed TagId constants (like the structural-predicate tags) or remain as a separate FeatureFamily enum. Today the two are intentionally distinct: categories drive generation placement; tags drive propagation filters and bulk modifier selection. The question is whether a future ADR should unify them so that propagation filters can use Feature category as a has_tag argument without an enum-to-tag translation step.

See also: pr-wave-roadmap.md § ADR-Category-vs-tag for the pending ADR stub.

Journal Readback And Annotation Implementation​

gd-journal.md defines the target Journal surface, but the first implementation wave still has two rollout questions:

  • Whether the first Journal/runtime alignment wave ships only the readable Journal prose while reserving a separate narration-safe readback surface for a later wave, or whether readable prose and spoken-readback prose ship together in the same implementation pass. The naming of any eventual runtime slots remains deferred.

  • Whether the first Journal wave ships only system-authored annotations (pin, likely/doubtful/disproved, bookmark) or also ships player-authored freeform notes on day pages from the start.

See also: pr-wave-roadmap.md § Wave J — Journal Runtime Alignment.

Universe-lore deferred names (Wave U exploration)​

These entries record names and canonical-term decisions that Wave U's exploration work surfaced but explicitly deferred. The entries are collected here so the bible-only and proposed-canon decisions stay visible across waves until the project owner commits answers.

1. Continent names (deferred by Wave U)​

The universe lore established that multiple continents exist (ul-cosmology.md), but no continent names are committed. The Valenar starting Zone is on one continent whose name is deferred. Question: what are the committed continent names, and which continent hosts Game 1? Status: proposed (canon-tier question requiring user decision).

2. God names and domains (deferred by Wave U)​

ul-divine-layer.md confirms gods exist and the pantheon is plural, but no individual god names or domains are committed to canon (the Game 1 ceiling rule caps exposure at hinted). Question: what are the hard-canon god names in the universe bible, for internal consistency even if Game 1 never reveals them? Status: bible-only-tier decision requiring user input.

3. Hero Order name (deferred by Wave U)​

lh-game1-cosmology-hooks.md references "an organized order predated the current era" and notes it is not named in Game 1. Question: what is the committed internal name for the historical Hero Order (for bible-only use)? Status: bible-only-tier decision.

4. Shroud as committed canonical term (proposed status)​

ul-shroud.md uses "Shroud" as the term for the phenomenon that impairs divine sight. This is currently used in universe lore but its canonical status should be committed. Question: is "Shroud" hard canon or soft canon at the universe level? Current recommendation: soft canon (it is the intended direction but has not been explicitly confirmed by the user as hard canon). Status: proposed → needs user confirmation to promote to soft canon or hard canon.

5. Accord of Intervention as committed canonical term (proposed)​

ul-hero-calling.md and lh-game1-cosmology-hooks.md reference the "Accord of Intervention" as the divine compact permitting Callings. Question: is this term hard canon for internal use? Status: proposed.

6. Demon Knight as committed canonical term (proposed)​

lh-game1-world-hooks.md references "Demon Knight rank" as a sub-King demon lord. Question: is "Demon Knight" a committed canonical term for the rank below Demon King? Status: proposed.

7. Corebound as committed canonical term and category-noun choice​

ul-hero-calling.md uses "Corebound" for the universe-scope pattern of mortals drawn to Wardhearts without a clean mark. lh-game1-cosmology-hooks.md notes the Game 1 protagonist's situation "suggests this pattern" but records the term itself as PROPOSED TERM. Two coupled sub-questions remain open:

  1. Is "Corebound" hard canon for internal use, or proposed?
  2. Is "Corebound" the right category-noun for the broader classification of "unindexed / unclaimed divine vessel" mortals at universe scope, or should a new category-noun be coined for that classification while "Corebound" stays a narrower descriptor (or is retired)?

Both sub-questions must resolve together because promoting the label without confirming the category scope would force a second rename. The term must remain PROPOSED TERM until both decisions land. Status: proposed → needs user confirmation.

8. ADR placement for gd-* files within docs/lore/ vs staying in flat directories​

Wave D's ADR (ad-0002-lore-docs-migration.md) resolves the deferral from pr-file-conventions.md line 39 by keeping gd-* files in their existing subdirectories. This is a Wave D decision. Question: is there any future driver to move gd-* files into a docs/lore/gd/ subtree? Current answer: no — the implementer's decision is to stay in-place. RESOLVED by Wave D ADR (2026-05-10). Closing this question; the resolution lives in ad-0002.

9. current-ux/ directory prefix scope​

Wave D renames only SCREENSHOTS_REFRESH.md (now pr-screenshots-refresh.md) in current-ux/. The screenshot PNG files and stage-0-mockups/ HTML are binary/non-md assets and are not renamed. Question: should a future wave establish a naming convention for the screenshot manifest files, or is the ad-hoc Playwright capture approach the permanent pattern? Status: open.

10. Hero vs Champion vs Called vs Vessel vs Unmarked — MC classification label​

ul-hero-calling.md uses "Hero Calling" and "Called hero" as the universe-scope phenomenon language; gd-glossary.md carries no committed entry for any of "Hero", "Champion", "Called", "Vessel", or "Unmarked"; gd-canon.md likewise commits no MC classification term; gl-mc-corebound.md uses "Hero Calling", "Called hero", and "Corebound" as descriptive / proposed language; and ul-divine-layer.md lines 30–36 already commit "Vessel" with a structural meaning at universe scope — "a mortal or mortal-adjacent entity that a god works through" — which would clash if "Vessel" were reused as the MC's label. Context: no committed glossary or canon entry exists for the MC's category label; "Hero" is morally loaded, "Champion" is candidate but undefined, "Called" is currently descriptive-only, "Vessel" already has a conflicting committed meaning at ul-divine-layer.md, "Unmarked" is candidate but undefined, and "Corebound" is PROPOSED TERM per Q7. Question: which (if any) of these is the canonical category label for the MC, and at what canonicity tier? Status: proposed → needs user confirmation.

11. Soul expansion / void summoning mechanism — does it exist at universe scope?​

This concept is explicitly absent from ul-hero-calling.md, ul-shroud.md, and ul-divine-layer.md; it has no current ul-* source and is a candidate-only concept awaiting a scope decision (universe vs game-local vs reject). Context: the candidate proposal is that summoning a mortal across the void / boundary enlarges or opens the soul (creating capacity that a god could fill at arrival), and in the MC's case the transit completed but no god-mark attached — leaving an open / unfilled capacity. No authority doc currently asserts or denies this mechanism. Question: should this concept be committed at universe scope (in ul-divine-layer.md or a new ul-* file), at game-local scope, or rejected entirely? Status: proposed.

12. Gods-cannot-find-MC framing — active universe-law, Shroud side effect, or simple mark-absence consequence?​

gl-mc-corebound.md lines 44–48 commit as hard canon at game-local scope that the mark did not attach and that Shroud-shielding does not apply to the MC's case; ul-divine-layer.md lines 64–69 commit at universe scope that gods are not omniscient of mortal events; ul-shroud.md lines 26–30 commit that the Shroud limits divine perception of mortals. Context: hard canon currently states only that the mark did not attach. Whether this makes the MC actively invisible / unindexed to divine perception (a structural consequence at universe scope), a Shroud-disruption side effect, or just an ordinary consequence of the mark not completing (with the MC still observable like any unmarked mortal) is undecided. Question: is "gods-cannot-find-the-MC" an active universe-law consequence, a Shroud-disruption side effect, or just a consequence of the mark not completing? Status: proposed → needs user confirmation.

13. MC advantage as broad learning / affinity — canonical layer and mechanism label​

gl-mc-corebound.md lines 58–63 commit as hard canon at game-local scope that the MC's edge is "mortal capability — Earth-origin background skills, individual aptitude, and acquired learning — not a god's gift"; gl-mc-earthborn-backgrounds.md lines 44–48 commit origin traits and skill affinities and lines 58–63 commit that Earth knowledge accelerates True Harm discovery; ul-hero-calling.md lines 55–60 commit by contrast that properly Called heroes receive a clean hero-class signature, which the Corebound pattern does not. Context: the negative framing (absence of god-bestowed powers) is committed hard canon at game-local scope; the positive framing of "broad learning / affinity" as a named canonical advantage-mechanism label is proposed and not yet committed at any tier. Question: should "broad learning / affinity" be committed as the MC's advantage-mechanism label at game-local scope (gl-mc-corebound.md), elevated to universe scope (ul-divine-layer.md), or left as the implicit consequence of "mortal capability" without a named mechanism label? Status: proposed → needs user confirmation.