Skip to main content

ADR 0006 — Dynamic Quest Pressure Model and Cross-Act Lane Architecture

Status​

Accepted — 2026-05-17.

Context​

The Valenar design intent has always combined an authored Act-arc story with a colony-builder economy that runs in parallel to the MC's exploration. As the project moved from prototype to integration, the user surfaced an explicit shift: keep authored quests, but stop relying on them as the primary engine of player progression. Quest pressure should become state-driven — emergent from Feature transitions, Territory knowledge advances, Site state changes, pressure escalation, settlement shortages, route safety, faction claims, NPC state, and authored story gates — and multi-threaded across the Saga Arc. Authored mission rungs would still anchor each cross-act lane, but the moment-to-moment "what should I be doing" signal would come from the world itself. This left several specific architectural questions open that needed user decisions before any new contract docs, lane docs, or runtime entries could be committed.

The first open question concerned where dynamic quest pressure should live. Two patterns were viable: fold the new generation contract into the existing ../../systems/gd-objectives-clues-missions.md planning-taxonomy doc, or author a new doc whose sole job is to specify the generator. Folding would have kept the surface count low but collapsed the planning taxonomy (which is normative for the Objective → Clue/Lead → Mission → Activity stack) with the generation contract (which is normative for the binding from world-state source facts to planning artifacts). Authoring a new doc keeps each surface single-purpose and makes the generator contract auditable on its own terms. The user chose the new-doc path; that doc became ../../systems/gd-dynamic-quest-pressure-model.md.

The second open question was the Interacting state drift. The Feature state ladder in ../../generation/gd-feature-generation-contract.md and the matching ladder in ../../generation/gd-territory-generation-contract.md both declared a 10-state form including an Interacting rung between Surveyed and Handled. The committed runtime enum examples/valenar/Generated/Territories/FeaturePlacement/FeaturePlacementTypes.cs carries a 9-state form without Interacting, and the drift was logged at ../../systems/gd-state-axes-and-thresholds.md line 96 as deferred. Wave Q forced resolution because the new dynamic quest pressure model binds to Feature state transitions and cannot reference a non-existent runtime state.

The third open question was whether the seven cross-act lanes that feed the Saga Arc — Core/Truth, Survival/Settlement, Pressure/Corruption, People/Retinue, Faction/Polity, Rune/Crafting/True Harm, Reclamation/Crown — require a new vocabulary tier above the existing Quest Thread tier. The taxonomy line in ../../systems/gd-quest-and-lore-design.md defined a Quest Thread as "multi-act objective ... resolves before the saga arc ends," which would have suggested some lanes (Core/Truth, Reclamation/Crown) need a new tier above Quest Thread because they resolve only when the saga concludes. Introducing a new tier (candidates considered: "Saga Thread", "Campaign Thread", "Lane") would have expanded the committed planning vocabulary at the highest authority level, with all the downstream cost that entails: documentation churn, agent-prompt updates, taxonomy-doc patches across the design tree, possible runtime-type additions, and a new question of whether existing act-scoped Act 0 thread owners (Survive, The Old Stones, The Ruin Beneath, Make This Place Hold) belong to the new tier.

The fourth open question came from an earlier assistant proposal: author a competing player-fantasy statement in a gd-* doc to mirror the ../../README.md premise so the design tree carries its own canonical premise surface. The user explicitly rejected this proposal. The README premise (lines 3–7) is the sole player premise; creating a parallel gd-* surface would have invited drift and required the project to keep two premise statements in sync forever.

These four questions resolved into the Q1–Q4 decisions below and were applied across Wave Q (docs contract, lane owner docs, ladder drift closure, Quest Hook surfaces, Journal extension, canon bullets), Wave M (act-doc cross-act lane visibility), and Wave D (roadmap, governance, ADR). This ADR records the four decisions for future waves and for verifier checks.

Decision​

Four decisions made in the Wave 0 → Wave Q → Wave M → Wave D orchestration:

Q1 — Drop Interacting from the recommended Feature state ladders​

The Interacting state previously appeared in ../../generation/gd-feature-generation-contract.md and in ../../generation/gd-territory-generation-contract.md as a 10-state ladder rung between Surveyed and Handled. The committed runtime enum examples/valenar/Generated/Territories/FeaturePlacement/FeaturePlacementTypes.cs carries a 9-state form without Interacting. The drift was logged in ../../systems/gd-state-axes-and-thresholds.md as deferred.

Decision: The 10-state ladder in both contract docs is updated to 9-state, matching the committed runtime enum. The drift note in ../../systems/gd-state-axes-and-thresholds.md is closed as "Not adopted." No Interacting state is preserved as an alias, default, or backwards-compatible synonym. New artifacts (e.g., ../../systems/gd-dynamic-quest-pressure-model.md) do not reference Interacting.

Q2 — Preserve examples/valenar/README.md as the sole player premise surface​

The Valenar player premise lives at ../../README.md lines 3–7. An earlier assistant proposal to author a competing gd-* player-fantasy doc was explicitly rejected.

Decision: The README premise stays verbatim. No gd-* player-fantasy or premise doc is authored. Cross-act lane owner docs may reference the README premise by link if needed; they do not duplicate it. ../../gd-canon.md may add short bullet-form acknowledgments of structural changes (lane model, failure-forward rule), but no competing premise statement.

Q3 — Cross-act lanes are Quest Threads with act_scope: cross-act; no new tier​

The Valenar Saga Arc is fed by seven cross-act lanes (Core/Truth, Survival/Settlement, Pressure/Corruption, People/Retinue, Faction/Polity, Rune/Crafting/True Harm, Reclamation/Crown). The existing Quest taxonomy in ../../systems/gd-quest-and-lore-design.md defined Quest Thread as "multi-act objective ... resolves before the saga arc ends," which would have suggested some lanes (Core/Truth, Reclamation/Crown) need a new tier above Quest Thread.

Decision: No new vocabulary tier is introduced. The seven cross-act lanes are Quest Threads with act_scope: cross-act. The taxonomy line is patched to read "Most resolve before the saga arc ends; some campaign-spanning lanes (such as the Core/Truth and Reclamation/Crown threads) run the full saga and resolve only when the Saga Arc itself concludes. All remain Quest Threads — no additional tier is introduced." Existing act-scoped Act 0 thread owners (Survive, The Old Stones, The Ruin Beneath, Make This Place Hold) coexist with the cross-act lanes; cross-act lanes do not subsume them.

Q4 — Apply Interacting removal across both feature and territory generation contracts​

The Q1 decision applies symmetrically: the 10-state ladder in ../../generation/gd-feature-generation-contract.md lines 488–499 AND the matching ladder in ../../generation/gd-territory-generation-contract.md lines 716–727 both lose the Interacting line. The drift-closure note in ../../systems/gd-state-axes-and-thresholds.md references both.

Decision: Both contract docs are updated in the same wave (Wave Q). The artifact class (Feature state ladder in docs) remains internally consistent.

Rationale​

Why drop Interacting from the doc rather than add it to the runtime. The committed runtime enum is the source of truth for what states the engine actually distinguishes. The 10-state doc ladder was speculative — no runtime, read-model, or test referenced Interacting. Adopting it would have required adding a new runtime state, propagating it through FeaturePlacementTypes.cs, the read-model projection, the SignalR wire shape, the React client, and every existing test fixture. None of that work had been planned, and none of the design problems the Wave Q dynamic-quest-pressure contract solves require Interacting to exist. The no-fallback redesign propagation rule in .claude/rules/orchestrator-mode.md § Source freshness and no-fallback redesign propagation resolves the tie: the committed form wins, the drifted form is closed, no alias is kept. Keeping Interacting in one doc while removing it from the other (or as a "deprecated alias") would have been exactly the kind of drift the rule forbids.

Why preserve the README premise. The user explicitly rejected the rewrite. Creating a parallel gd-* premise surface would have invited the project into a forever-sync problem between two canonical premise statements. The README is the canonical entry point for anyone encountering Valenar for the first time, and the existing ../../gd-canon.md and ../../gd-glossary.md surfaces already absorb the supporting canon and term definitions; no parallel premise doc is needed. The lane owner docs cross-reference the README by link, which gives readers one click to the authoritative source. Wave Q's ../../gd-canon.md bullets are structural notes (the lane model, the failure-forward rule) — they do not author a competing premise.

Why no new tier above Quest Thread. Introducing a tier name ("Saga Thread", "Campaign Thread", or "Lane" as a tier word) would have expanded the committed planning vocabulary at the highest authority level without architectural payoff. The existing Quest Thread tier already supports the cross-act case once the taxonomy adds an act_scope qualifier — that is a precision tweak, not a structural addition. The downstream cost of a new tier (documentation churn across the design tree, agent-prompt updates, possible runtime-type addition, a new question about act-scoped Act 0 thread owners) outweighs the clarity gain. The taxonomy patch — "most resolve before saga arc ends; some campaign-spanning lanes run the full saga" — captures the only real distinction (when the lane resolves) without committing a new noun. The Saga Arc remains the multi-act outcome envelope above the lanes, and whether it deserves its own committed vocabulary tier is tracked separately as Q-OQ-1 in ../../implementation/pr-open-questions.md.

Why apply the Interacting removal to both contracts in the same wave. The no-fallback redesign rule requires the redesign to override the entire artifact class. The artifact class here is "the Feature state ladder as authored in the generation contract docs." Leaving Interacting in one contract while removing it from the other would have produced exactly the silent drift the rule forbids: future readers would have to choose which contract was authoritative, future verifier checks would have to specially case one doc, and the next wave to touch either contract would inherit the inconsistency. Applying the change symmetrically in Wave Q closes the entire artifact class in one pass.

Consequences​

For future doc authoring. No new doc may reference Interacting as a Feature state; the 9-state form is binding. The committed runtime enum examples/valenar/Generated/Territories/FeaturePlacement/FeaturePlacementTypes.cs is the source of truth and cannot be extended with Interacting unless this ADR is explicitly superseded. No new doc may author a competing player premise; the README premise is the sole surface and new lore or quest docs must cross-reference it by link rather than restating it. New cross-act narrative content must classify itself as a Quest Thread (not a new tier) and carry act_scope: cross-act in its frontmatter or top-of-doc metadata. Authored mission rungs (Wave QL output) must use the seven committed lane keys verbatim: core-truth, survival-settlement, pressure-corruption, people-retinue, faction-polity, rune-crafting-true-harm, reclamation-crown.

For future runtime authoring (Waves QP / QL / QF / QR). The DynamicQuestPressureGenerator must emit lane-tagged artifacts using the seven committed lane keys; no eighth key may be added without amending this ADR. The runtime FeaturePlacementTypes.cs enum may not be extended with Interacting. Read-model fields added in Wave QR may carry a LaneName: string field — the open question Q-OQ-4 in ../../implementation/pr-open-questions.md tracks whether LaneName should be promoted to a typed enum after Wave QL locks the authoring pattern. The Generator Contract Rules in ../../systems/gd-dynamic-quest-pressure-model.md are binding for every generated artifact; a generated mission without all five rule fields must be rejected (not silently defaulted) per the no-fallback tenet.

For verifier checks. Any future verifier — explorer, validator, or tenets-check — must enforce three guards derived from this ADR. First, no Interacting references appear in any live doc other than the historical-mention in the closed drift note at ../../systems/gd-state-axes-and-thresholds.md line 96; the verifier must allow the historical mention but reject any new authored use. Second, no competing player-premise text appears in any gd-* doc; the README premise must remain the sole canonical surface. Third, no new tier vocabulary appears in ../../systems/gd-quest-and-lore-design.md or in any other authority surface; "Saga Thread", "Campaign Thread", and "Lane" as a tier word are not committed vocabulary, and any future proposal to introduce one requires superseding this ADR.

For ADR ownership. This ADR is at the Valenar game-design layer, not the engine/compiler layer. It belongs in examples/valenar/docs/lore/adr/, not the workspace-root docs/decisions/ tree which holds engine and compiler decisions per ad-0004-lore-adr-folder.md. Future ADRs that govern the dynamic quest pressure runtime or the cross-act lane model belong in the same Valenar ADR folder and should cite this ADR.

References​