Authored gates, triggers, and quests: decision-complete design

[mmacy]

Note

As built (2026-08-07): the osrlib slice — delivery-order item 1 — is complete: spec derivation in #49, phases 10–15 as PRs #50–#61 plus a phase 16 documentation refresh (#62, #63), and the osr-forge gap recorded in mmacy/osr-forge#39. docs/spec.md is now the authority; where the implementation departs from this body, the as-built comment records each delta. Remaining from the delivery order: the osr-web and osr-editor phases.

Important

This is the authoritative, decision-complete design for authored gates, triggers, and quests
across osrlib, osr-web, and osr-editor, filed here because osrlib is the schema's authoritative
home. Every design question it raises, it settles; every load-bearing claim about current
behavior has been verified against the code of all three repos. The next step is deriving the
osrlib spec from this design. Implementation follows the delivery order below.

Problem

An osrlib adventure can be lost but not won. The engine's only terminal state is a battle TPK
(SessionMode.GAME_OVER, assigned solely at battle.py:542); there is no victory, no authored
objective, and no completion detection at any granularity. Content wiring — the lever that opens
the portcullis, the key that fits the lock, the idol the temple pays for — is possible only in
bespoke game code via osrlib's extension surface (event listeners, session flags, referee
commands). Nothing about it is authorable: the adventure document has no field for it, osr-web has
no UI for it, and osr-editor has nothing to edit.

Current state, verified across the three repos

• osrlib's Adventure model carries exactly name, description, hooks, town, dungeons,
  monsters (crawl/adventure.py:47-67). hooks is inert prose — osr-web renders it as town
  "rumors" and nothing ever references it mechanically.
• There is no item-identity surface for authored objects. The adventure document can define
  custom monsters (Adventure.monsters unions bundled MonsterTemplates into the base catalog
  via _effective_monsters, crawl/adventure.py:94, with collision reporting) but not custom
  items. The equipment catalog is four typed template tuples — WeaponTemplate,
  ArmourTemplate, GearTemplate, AmmunitionTemplate (core/items.py:320) — each template
  carrying an item_type discriminator and an id. Hand-placed cache contents already reference
  catalog ids (FeatureSpec.item_ids and magic_item_ids, crawl/dungeon.py:365), GrantItem
  validates against the catalog (commands.py:1459), and ItemAcquiredEvent.item_ids carries
  catalog ids — so the placement, grant, and observation machinery all exist and all speak
  catalog ids; what is missing is a way for an adventure to mint one. Named valuables
  (ValuableSpec, crawl/dungeon.py:293-308) carry kind/name/value/weight and no id, so a taken
  valuable is invisible to event matching.
• The extension surface a quest system rides on all exists and is serialized in saves: listener
  protocol and state store, session.flags, SetFlag/AwardXP/GrantCoins/GrantItem, and
  trigger-suitable events (LocationEnteredEvent, ItemAcquiredEvent, MonsterDefeatedEvent).
  FlagSetEvent is referee-visibility by design — content wiring is the game's secret.
• The replay contract constrains where an interpreter can live. Replays rebuild state by
  re-executing the command log with no listeners registered; listener-issued commands are already
  in the log (persistence.py:281-331; osrlib docs/spec.md: "replays reproduce engine state
  exactly with or without listeners"). An always-on interpreter inside the session would fire
  again during replay and double-issue its consequences.
• Doors are authorable as locked (DoorSpec, dungeon.py:183-196) but the only player-facing
  unlock is the thief's PickLock (ForceDoor explicitly defers: "locked doors need PickLock,
  not muscle"). There is no key-item concept. The referee command SetDoorState
  (commands.py:1631) can rewrite any door's overlay anywhere — the lever-opens-portcullis
  primitive — but nothing authored drives it.
• osrlib's spec (docs/spec.md:171) excludes quest systems from the library: "game-design
  systems with no SRD basis — quests, achievements, story progression, dialogue — belong to the
  game." The same spec's session-flags bullet names "a lever in room 3 opens the portcullis in
  room 12" as something dungeon content reads flags for — so the gates layer is close to
  blessed already, and the quest layer arrives as a first-party implementation of the documented
  extension surface rather than a new in-session system.
• The one worked example in the ecosystem is examples/tui_crawler/quest.py — an 80-line fetch
  quest listener, deliberately outside the library, written as proof that the extension surface
  is sufficient for game authors. It matches its idol by display name because there is nothing
  else to match on. It is not a surface adventure authors can reach.
• osr-web consumes only the six Adventure fields; PlayerView (crawl/views.py:134-156) is a
  closed whitelist with no field for flags, progress, or objectives — session.py:802-804
  asserts the exclusion — so quest state has no route to a client by construction, and no
  consumer can evaluate conditions itself. Its transcript log is ephemeral (wiped on every game
  entry); it has a deterministic narrator (server/narrate.py) plus an LLM overlay
  (server/narration.py) whose per-event tone hints are hardcoded. It explicitly swallows
  FlagSetEvent.
• osr-editor has zero quest code, but its spec anticipated this feature: quests are a named
  future extension (docs/spec.md:267) with the growth path pre-written — osrlib owns the
  schema, generated types pick it up, ops grow additively, triggers place on the map the way
  transitions do, diagnostics lint dangling quest references the way they lint monster ids.

Design overview

Three layers. Mechanics are two primitives — gates and triggers — with quests composed from both.
Narrative is authored text attached to mechanical objects. Presentation is who renders that text.

The two primitives live at different depths of the engine, and that layering is itself a design
commitment:

• Gates are in-engine command-legality checks, evaluated exactly the way locked is today.
  They mutate nothing, so replay is unaffected.
• The trigger/quest interpreter is a library-shipped Listener that games register — the
  existing extension contract. Everything the interpreter does lands in the command log as
  ordinary commands, and all quest, trigger, and journal state is engine-owned session state
  mutated only by those commands — so a replay, which runs with no listeners, rebuilds quest
  state exactly by re-executing the log. The interpreter holds no state of its own that the
  engine cannot reconstruct.

This layering also resolves the library-posture tension: gates are dungeon furniture osrlib's
spec already gestures at, and the quest layer arrives as a first-party implementation of the
documented extension surface.

Item identity

The adventure document gains bundled item definitions, mirroring the Adventure.monsters
precedent exactly:

• Adventure.items is a tuple of item templates — the existing WeaponTemplate | ArmourTemplate | GearTemplate | AmmunitionTemplate union, discriminated on the item_type
  field each template already carries. A quest key or idol is authored as a GearTemplate; the
  surface does not artificially exclude a named weapon or armour piece.
• An _effective_items union (mirroring _effective_monsters) merges bundled templates into the
  base equipment catalog at session start and inside validate_adventure. Shipped ids win;
  collisions are reported exactly as monster template collisions are.
• Everything downstream is existing machinery, unchanged: bundled items place in caches through
  FeatureSpec.item_ids, GrantItem grants them because it validates against the effective
  catalog, ItemAcquiredEvent carries their ids because it already carries catalog ids, and
  validate_adventure resolves every item reference against the effective catalog.

ValuableSpec stays id-less. Valuables remain generic, sellable treasure; a MacGuffin is an
authored item placed in a cache, not a valuable. This keeps exactly one item-identity namespace —
the catalog — and eliminates the display-name matching the worked example was forced into. If a
"this specific gem is also a quest target" need ever materializes, an optional id on
ValuableSpec can arrive additively; nothing here forecloses it.

Conditions and gates

A condition is a deterministic predicate over session state, evaluated live at the moment the
gated thing is attempted (level-triggered, not edge-triggered). Live evaluation is the point: a
flag set at item pickup drifts from the truth when the party drops or sells the item; a predicate
checked at use time cannot. The vocabulary:

• has_item(item_id, consumes=False) — some party member's carried inventory contains an item
  whose catalog id (equipment or magic-item) matches. Any member's carried inventory is the whole
  test: items live in member inventories (GrantItem takes a character_id), there is no shared
  pile, and equipped-only would break the toll-coin case. With consumes=True, one instance is
  removed when the gated command succeeds — consumption is an effect of the successful command,
  reported through its events, never a side effect of condition evaluation, which stays pure
  (this is what keeps the gates-mutate-nothing replay argument true). The instance is taken from
  the first holder in party order.
• flag_equals(key, value) — a session flag holds a value.
• effect_active(kind) — an active effect whose EffectDefinition.kind matches is attached to
  a party member (the light precedent: authors choose between "merely carrying the talisman
  suffices" and "you must invoke it").

Conditions form a discriminated union that grows additively — this union is the primary seam for
future condition kinds (NPC-related conditions among them).

A gate is an optional requires condition on an interaction spec. Version one scopes gates to
DoorSpec.requires and TransitionSpec.requires — specs that content packs do not carry (see
the packs seam). Two further gate sites are part of the design but trail the first slice, riding
the pack-interaction decision when it comes: TrapSpec.bypass (the trap does not spring for a
party meeting the condition) and condition-keyed prose variants on AreaSpec/FeatureSpec
descriptions (the feather-holder notices the draft, the scroll-bearer reads the inscription).
When prose variants land they are engine-resolved — see the visibility section.

Gates and the lock machinery

requires and locked are orthogonal layers, not one mechanism. Unifying them — re-expressing
locked as a built-in gate — was considered and rejected: locked is SRD-grounded, stateful,
edge-triggered mechanics (thief skill rolls, per-character lockouts, overlay mutation on
success), while a gate is a stateless authored predicate. Merging them would force dice,
character state, and lockout tracking into the condition union — a merge of unlikes that reads
as simplification and is not.

The composition rules:

• When a door carries both, the lock and the condition must each be satisfied to operate it.
• PickLock addresses only the lock, never the gate. A thief is not a universal quest bypass;
  an author who wants a pickable obstacle authors locked without a gate.
• SetDoorState rewrites the state overlay only and never touches requires — specs are
  immutable ("play mutates the overlay, never this spec").
• A door standing open admits passage without a gate check. Triggers open gated doors by setting
  them open, not by clearing the gate — the portcullis raised by the lever is open regardless of
  what raising it by hand would require. If the door closes again, the gate re-applies; live
  evaluation stays meaningful.
• A gate refusal is a command rejection with its own codes — exploration.door.gate_refused and
  exploration.transition.gate_refused — distinct from exploration.door.locked, with the
  gate's authored refusal text carried alongside the code so the renderer can show it. Success
  text rides the normal door and transition events as an optional authored beat.

Triggers

A trigger is an authored binding: when an observable event matches a pattern (optionally further
gated by conditions), issue referee commands. Edge-triggered. The observables are the existing
events (LocationEnteredEvent, ItemAcquiredEvent, MonsterDefeatedEvent, FlagSetEvent);
the consequence surface authors reach is the existing referee command vocabulary (AwardXP,
GrantCoins, GrantItem, SetFlag, SetDoorState, SpawnMonsters, SpawnNpcParty). The
semantics:

• Once-only by default, with repeatable: true as the authored opt-in. Once is the common
  authored case (the ambush, the reveal, the reward) and caps cascade blast radius. Fired-state
  is engine session state (see the interpreter section), so once-only survives save/load and
  rebuilds under replay.
• Deterministic ordering. Multiple triggers matching one event fire in document order —
  stable and author-controllable. Consequences within a trigger execute in authored order. All
  consequences of a batch execute before any subsequent player command.
• Bounded cascades. SetFlag is a consequence and FlagSetEvent is an observable, so
  trigger chains are constructible — and flag-chains are legitimate wiring, so the answer is a
  bound, not suppression. Events produced by a player command are depth 0; events produced by a
  trigger's consequences are one deeper than the events that fired it. Triggers match events of
  depth 4 or less; deeper events are not offered to the interpreter, and truncation records a
  referee-visibility note. The editor carries an advisory cycle lint (see consumers); runtime
  boundedness is the guarantee, so a cycle is suspicious authoring, not invalid content.
• Rejected consequences are dropped and recorded. Referee spawns reject when an encounter is
  already open — and MoveParty can emit LocationEnteredEvent and open a wandering encounter
  in the same command result, so "ambush at the shrine" can collide with a random encounter
  immediately. A dropped consequence records a referee-visibility note; the editor lints
  collision-prone pairings. No retry or queue — deferred consequences firing later would be
  undebuggable.
• Rewards and treasure XP. Trigger-granted treasure follows the same valuation rules as any
  treasure at the moment it lands: granted mid-dungeon it counts in the next return delta;
  granted at town it lands outside any delta and earns no treasure XP. No valuation bookkeeping
  is added or changed. Authored XP belongs in AwardXP — treasure XP is for recovered treasure —
  and the editor carries an advisory lint for a coin or item reward with no accompanying
  AwardXP.
• Timing honesty. MonsterDefeatedEvent emits at battle end, so "the portcullis opens the
  moment the boss falls, mid-fight" is not authorable in version one. Stated so authors'
  expectations are set.

The interpreter and the command log

The interpreter observes events, decides, and acts exclusively by issuing commands — because
replays run with no listeners, anything the interpreter merely remembered would be lost to a
replay. Quest, trigger, and journal state therefore live in the engine session, mutated only by
a small family of lifecycle referee commands the interpreter issues (authors author QuestSpecs
and triggers, never these commands):

• MarkTriggerFired(trigger_id) — records the fired mark in session trigger state and emits a
  referee-visibility TriggerFiredEvent. Issued before the trigger's consequences.
• ActivateQuest(quest_id), RevealObjective(quest_id, objective_id),
  CompleteObjective(quest_id, objective_id), CompleteQuest(quest_id) — advance session quest
  state; their execution reads the QuestSpec from the adventure document, emits the
  player-visible events carrying the authored narrative, and appends the journal entries.
  CompleteQuest on a quest marked as concluding the adventure transitions the session to
  victory (below).
• AddJournalEntry(...) — appends a journal entry outside a quest lifecycle beat; how one-off
  triggers get a journal voice.
• RecordNote(...) — no state effect; emits a referee-visibility event. The mechanism behind
  the dropped-consequence and cascade-truncation records, and generally useful to game-side
  listeners.

These are ordinary logged, replayed commands; re-executing them rebuilds quest state, journal,
and fired-marks exactly, with no interpreter present. In addition, the base Command gains an
optional source: str | None = None field — ignored by execution, additive within the schema
version, replay-safe — which the interpreter stamps with the owning trigger or quest id on every
consequence it issues. Without it, "why did the party get 500 XP" is unanswerable from the log.

Quest reward commands issue immediately after CompleteQuest, in authored order, before any
subsequent player command.

Quests

A QuestSpec composes the primitives:

• id, name, and a narrative block
• Activation: a quest is dormant until its activation trigger fires; a quest with no
  activation trigger is active from session start. There is no accept/decline interaction — a
  B/X module frames the objective, it does not negotiate. The offer beat displays at activation.
• Objectives: each an authored trigger plus narrative, optionally hidden. A hidden objective
  reveals when its optional reveal trigger fires, or on completion if it has none.
• Rewards: referee commands issued on completion.
• Completion rule: all objectives, or any.
• An optional marker designating that completing this quest concludes the adventure.

The journal

The journal is an appended, event-sourced list in session state — never derived on demand.
Entries append when beats land: quest activation, objective reveal and completion, quest
completion, and any one-off trigger whose narrative block carries a journal form. Appending
preserves order-of-discovery, keeps beats whose source state has since changed (the third firing
of a repeatable trigger, a revealed-then-completed objective), gives triggers a journal voice
without a quest attached — and derivation is foreclosed anyway, since consumers cannot evaluate
quest state by construction. The journal persists in saves and ships to clients verbatim through
PlayerView.

Narrative blocks

Every mechanical object (quest, objective, gate, trigger) carries an optional narrative block
with three distinct audiences:

• Display beats — text the deterministic renderer shows verbatim: offer, progress, and
  completion text for quests; refusal and success text for gates ("the door doesn't budge; a
  shallow slot suggests something might fit"); fired text for triggers.
• Journal form — the entry recorded when the beat lands, phrased for a persistent journal
  rather than a transcript.
• LLM guidance — authored steering that is never displayed verbatim. The guidance field
  lives on the narrative block itself, so every object that carries narrative carries steering
  uniformly, plus one ambient guidance slot per dungeon level ("this level should feel
  increasingly wrong the deeper they go" attaches to no mechanical object). No other scoping
  machinery: guidance applies while its carrier is in play — quest active, gate encountered,
  trigger fired, level occupied. Trust posture: guidance is trusted as content, the same posture
  as description prose, which already flows into narration prompts today.

An optional speaker attribution stays free prose (see the NPC seam).

Visibility

Player-visible events carry authored text; the wiring that produced them — flags, conditions,
trigger internals — stays referee-only. The new player-visible event kinds are the quest
lifecycle events (QuestActivatedEvent, ObjectiveRevealedEvent, ObjectiveCompletedEvent,
QuestCompletedEvent), JournalEntryAddedEvent, and AdventureCompletedEvent; the new
referee-visibility kinds are TriggerFiredEvent and the RecordNote event. Gate refusal text
rides the command rejection; gate success text rides the existing door and transition events.

Condition-keyed prose variants, when they land, are engine-resolved at emission time and
shipped as text. Consumers cannot evaluate conditions by construction (PlayerView is a
closed whitelist and the flags exclusion is asserted in code), and growing a consumer-facing
condition surface would breach the backend-is-authoritative division all three repos are built
on. Engine-side resolution also keeps the secret wiring secret: the client sees the resolved
prose, never the condition.

PlayerView gains active quests (id, name, display narrative, visible objectives and their
states) and the journal.

Victory and session end

Adventure completion gets both a terminal event and a terminal mode: CompleteQuest on the
concluding quest emits a player-visible AdventureCompletedEvent carrying the authored
completion narrative and transitions the session to SessionMode.VICTORY (wire value
"victory"), a terminal mode mirroring GAME_OVER — play commands are illegal, referee
commands remain legal (which is also what lets rewards land after the transition).

The session concludes rather than continuing. The adventure module is the playable unit
throughout the ecosystem; campaign continuity is a non-goal; and post-victory play drags in a
swamp of underspecified questions (what is legal after winning, does XP accrue, can you die
after victory). Concluding now and adding a post-victory mode later is additive; shipping
"continue" first and tightening later is breaking.

This work also fixes an existing gap in the terminal-state machinery rather than inheriting it:
a non-battle party wipe (trap, deprivation) currently leaves the session in EXPLORING forever.
Non-battle wipes route to GAME_OVER. The delicate machinery is opened once, for both changes.

Engine changes implied

• Adventure.items and the _effective_items union, at session start and in validation
• Gate evaluation in the command handlers — a legality check beside locked, plus the
  gate-refusal rejection codes and the consume-on-success effect
• The trigger/quest interpreter as a library-shipped Listener; the quest lifecycle referee
  commands; the optional source field on the base Command
• Session state for quest, trigger, and journal progress, persisted in saves
• PlayerView additions: active quests, journal
• The new player-visible and referee-visibility event kinds
• SessionMode.VICTORY, AdventureCompletedEvent, and the non-battle-TPK routing to GAME_OVER
• validate_adventure grows hard reference checks — item ids in conditions, caches, and
  consequences against the effective catalog; monster, area, and dungeon/level references in
  triggers and transitions; quest and objective ids in lifecycle references

Consumers

• osr-web: registers the library interpreter; the renderer passes authored text through; a
  persistent journal panel (distinct from the ephemeral log); a victory screen on
  SessionMode.VICTORY; the LLM narration prompt gains active quest state, recent journal
  entries, and authored steering — replacing or augmenting today's hardcoded tone hints.
• osr-editor: regenerated types pick up the schema; the ops vocabulary grows additively; a
  quests panel joins the nav (an eighth target); gates and triggers place on the map the way
  transitions do. Lint grows: dangling-reference diagnostics mirroring validate_adventure;
  advisory lints for flag reads with no writer, trigger cycles, collision-prone
  trigger/encounter pairings, and treasure rewards with no accompanying AwardXP; and a
  reachability class ("door requires a key that is not placed anywhere") scoped to the decidable
  core — an id appearing in no cache, no trigger consequence, and no purchasable catalog entry —
  and advisory forever, because trigger-granted items and random treasure make the general
  problem undecidable, and lint warns while only validate_adventure gates publish.

Delivery order

1. osrlib — the schema and engine work, spec first. Everything downstream hangs off it. The
   slice that ships the interpreter also converts the worked example: examples/tui_crawler
   registers the library interpreter and authors its fetch quest as data in its adventure
   document, and the hand-rolled quest.py listener is deleted. Its job was proving the
   extension surface sufficed; once the library ships the interpreter, its job is demonstrating
   the authored surface, and keeping the hand-rolled version would leave two quest patterns in
   the repo. Closing deliverable of this phase: file the osr-forge issue recording the
   overrides-vocabulary gap (see the forge seam).
2. osr-web — prove the model plays before freezing authoring on it: interpreter
   registration, journal, victory, LLM context.
3. osr-editor — the authoring surface, as its spec already prescribes.

The first slice is gates on doors and transitions. It is the right first slice not because it is
small and independent but because its tiny surface area forces the two hardest schema questions —
item identity and lock composition — while everything else is still cheap to change, and it
pressure-tests the condition vocabulary before quests build on it.

Seams and scope guards

NPCs: seam only, not folded in

osrlib's spec puts dialogue in the same belongs-to-the-game exclusion as quests, and an NPC model
without dialogue is just prose — which narrative blocks already carry. The engine already has
NPC-shaped verbs (SpawnNpcParty — whose docstring names quest listeners as an intended caller —
and Parley); what it lacks is persistent named NPC entities, which nothing here requires. The
seam commitments:

• Conditions and triggers are discriminated unions; spoke_to(npc_id) or npc_present arrive
  later as additive variants.
• Narrative speaker stays free prose now; a typed npc_id arrives alongside it additively
  when NPCs land. Prose is never retrofitted into a reference.
• NPCs get their own id namespace when they arrive; the dangling-reference lint pattern extends.
• The consequence surface is "referee commands," full stop — already open.
• No closed enumerations anywhere an NPC would eventually slot (no literal "town" as the only
  quest source, no "monsters" as the only encounterable thing).

Adventure hooks

hooks stays exactly as it is: inert, diegetic rumor prose. With quests carrying offer
narrative, the document has two "why the party goes" surfaces, and the overlap was examined
deliberately: they are different registers — rumors are town color a game renders
atmospherically, offers are the mechanical entry beat of a specific quest — and neither subsumes
the other. No unification, and no mechanical linkage from a rumor to a quest id; if a typed
linkage ever wants to exist it arrives additively, under the same rule as speaker (prose is
never retrofitted into a reference).

Forge-backed projects

Quest authoring is native-project-only at first. In a forge-backed project the editor writes
overrides.yaml — osr-forge's schema — and that schema has no quest surface; growing one is
osr-forge's decision, made in its own repo against a settled osrlib schema. The editor disables
quest surfaces in forge-backed projects with an affordance explaining why. No shim is built:
this is sequencing, not accommodation, and the osr-forge issue recording the vocabulary gap is a
closing deliverable of the osrlib phase, not a someday.

Content packs

Quests are adventure-scoped and stay out of packs. The deferral has a sharp edge the v1 scoping
exists to blunt: ContentPackEntry embeds FeatureSpec, trap, and treasure directly
(crawl/content_pack.py:104-107), so a gate on those specs would ride into arbitrary target
adventures — carrying dangling item and flag references — the same release it shipped. Hence
gates v1 lands on DoorSpec/TransitionSpec only (which packs do not carry), and
TrapSpec.bypass plus prose variants ride the pack-interaction decision when it comes. Pack
features referencing item ids reference the shipped catalog only — adventure-bundled item ids
are adventure-scoped by construction, and pack insertion validates references against the target
adventure's effective catalog.

Serialization and versioning

Everything here is additive and nothing bumps SCHEMA_VERSION:

• New optional fields (requires, Adventure.items, Command.source, narrative blocks) and
  new event types are within-version by written policy (versioning.py:30-38).
• The new save-state blocks (quest, trigger, journal state) are new optional fields — same rule.
• Adding the SessionMode.VICTORY value is additive-within-version, and this work codifies that
  rule into the versioning policy: a new enum value has the same risk profile as a new event
  type, which the policy already blesses — old artifacts never contain it, and an older reader
  rejecting a newer artifact is a possibility the new-event-type rule already accepts. (The
  existing docstring says changing wire values is a bump; adding one is now addressed in
  writing, so the next addition does not reopen the question.)

The design of the shared single SCHEMA_VERSION integer itself — one number across saves,
characters, parties, packs, and stamped documents — is out of scope here; it deserves its own
issue if a bump-forcing change ever approaches. The editor's canonical-serialization
byte-stability invariant must hold for documents that use none of the new fields, and its
open-fields fidelity guard already protects older editors from newer documents in the interim.

Commitments at a glance

• Item identity: Adventure.items bundles existing item templates into the effective catalog,
  mirroring monsters; ValuableSpec stays id-less.
• Gates: in-engine legality checks on DoorSpec/TransitionSpec; conditions are has_item
  (any member's carried inventory, optional consume-on-success), flag_equals,
  effect_active(kind).
• Locks: orthogonal to gates; both must pass; PickLock never bypasses a gate; SetDoorState
  never touches requires; an open door admits passage; distinct gate-refusal rejection codes.
• Triggers: once-only default, document-order firing, cascade depth bounded at 4, rejected
  consequences dropped and recorded, treasure rewards follow normal valuation with authored XP
  via AwardXP.
• Interpreter: library-shipped Listener; all state engine-owned and command-mutated (lifecycle
  referee commands); optional source provenance on every command.
• Quests: activation-trigger model, no accept/decline; hidden objectives reveal by trigger or on
  completion; rewards issue immediately on completion.
• Journal: appended event-sourced session state, shipped verbatim in PlayerView.
• LLM guidance: on the narrative block uniformly plus a per-dungeon-level ambient slot; trusted
  as content.
• Visibility: player-visible events carry authored text; wiring stays referee-only; prose
  variants engine-resolved.
• Victory: SessionMode.VICTORY plus AdventureCompletedEvent; the session concludes; the
  non-battle-TPK gap routes to GAME_OVER in the same work.
• Worked example: examples/tui_crawler/quest.py is deleted in the slice that ships the
  interpreter; the example authors its quest as data.
• Adventure.hooks: kept as inert rumor prose; distinct register from quest offers; no
  mechanical linkage.
• Forge: native-only first; the vocabulary-gap issue files at the close of the osrlib phase.
• Versioning: fully additive; no SCHEMA_VERSION bump; the enum-value-additive rule gets
  written into the policy.

Non-goals

• NPC entities, dialogue systems, and any interaction surface beyond what Parley already does
• Branching narrative or dialogue trees
• Quest accept/decline interactions
• Post-victory play (additive later if ever wanted; concluding is the v1 semantics)
• Procedurally generated quests
• Quest content in content packs
• Campaign or multi-adventure continuity

Key references

• osrlib: crawl/adventure.py:47-67 (Adventure), crawl/adventure.py:94 (_effective_monsters,
  the union pattern items mirror), core/items.py:320 (EquipmentCatalog and its four template
  tuples), core/effects.py:464 (EffectDefinition, whose kind is the authorable effect
  identity), crawl/dungeon.py:183-196 (DoorSpec), crawl/dungeon.py:214-228 (TransitionSpec),
  crawl/dungeon.py:293-308 (ValuableSpec — no id field), crawl/dungeon.py:365 (FeatureSpec,
  whose item_ids/magic_item_ids place catalog items in caches), crawl/commands.py:95
  (SessionMode), crawl/commands.py:1459-1714 (referee commands incl. SetDoorState:1631,
  SpawnNpcParty:1596), crawl/commands.py:384 (PickLock), crawl/events.py
  (LocationEnteredEvent:94, ItemAcquiredEvent:202, MonsterDefeatedEvent:502,
  FlagSetEvent:660), crawl/views.py:134-156 (PlayerView), crawl/session.py:802-804 (the
  flags exclusion), crawl/battle.py:542 (the only terminal state), persistence.py:281-331
  (replay without listeners), versioning.py:30-38 (additive-within-version policy),
  crawl/content_pack.py:104-107 (packs embed FeatureSpec), docs/spec.md:169-176 (extension
  points, incl. the lever/portcullis line), examples/tui_crawler/quest.py (the hand-rolled
  listener this design retires)
• osr-web: server/narrate.py (deterministic renderer), server/narration.py (LLM tone hints),
  server/library.py:49-127 (raw-JSON metadata path), static/app.js:3234 (ephemeral log)
• osr-editor: docs/spec.md:267 (the quests future-extension entry), src/osreditor/ops.py
  (the op vocabulary), src/osreditor/lint.py (the lint rule set)

[mmacy]

Recommended split into agent-sized phases

This design decomposes cleanly along its own seams. The recommendation: one spec-derivation PR up front, then six new roadmap phases in docs/spec.md — numbered 10–15 below for reference; final numbering lands with the spec PR — each shipped through the standard phase loop (plan PR, then implementation PR). Each phase is scoped so a single agent can hold the whole thing in context: a bounded file surface, a milestone tests can verify, and vocabulary settled by earlier phases rather than negotiated mid-implementation.

Step 0 — derive the spec (one PR, not a phase)

Amend docs/spec.md once, covering all six phases: the schema contracts (condition union, narrative block, trigger and quest specs, lifecycle commands, session-state blocks), the revised extension-points language (the "quests belong to the game" sentence becomes "the library ships a first-party interpreter of its own extension surface; game-design systems beyond it belong to the game"), the additive-enum-value versioning rule, and the roadmap entries. After this PR, every phase plans from the spec, not from re-reading this issue — that is the main defense against an agent drifting from settled decisions or re-litigating them.

Phase 10 — item identity

Adventure.items, _effective_items mirroring _effective_monsters, collision reporting, and validate_adventure resolving item references (caches, grants) against the effective catalog. Nothing else. Phase 9 is the literal precedent to crib from, which makes this the ideal opening move.

Milestone: a bundled GearTemplate places in a cache via FeatureSpec.item_ids, grants via GrantItem, and surfaces in ItemAcquiredEvent by catalog id; a colliding id reports exactly as a monster-template collision does.

Design sections: Item identity.

Phase 11 — conditions, gates, and narrative blocks

The condition union (has_item, flag_equals, effect_active), requires on DoorSpec and TransitionSpec, the gate-refusal rejection codes, consume-on-success, the lock-composition rules, and the narrative-block model in its full three-audience shape (display beats, journal form, LLM guidance) — defined here because gates are its first consumer, then reused unchanged by every later phase. validate_adventure grows condition item-id checks.

Depends on phase 10 (has_item resolves against the effective catalog). Phases 10 + 11 together are the design's named first slice: the two hardest schema questions — item identity and lock composition — still resolve before anything builds on them; they just land as two PRs instead of one.

Milestone: a golden scenario in which a door gated on a key refuses with authored text and its own rejection code (consuming no draws and no time), passes once any member carries the key, and a toll-coin transition consumes on success; a locked-and-gated door requires both; SetDoorState opens a gated door and the gate re-applies when it closes.

Design sections: Conditions and gates, Gates and the lock machinery, Narrative blocks (the model only — guidance has no consumer yet).

Phase 12 — terminal modes (order-independent)

SessionMode.VICTORY with its command-legality rules (play commands illegal, referee commands legal), and non-battle party wipes routing to GAME_OVER. VICTORY is unreachable until phase 15 wires CompleteQuest to it — fine and additive; the point is the delicate terminal-state machinery opens once, for both changes. This phase touches session and battle code, not the adventure schema, so it can land any time before phase 15, including in parallel with 10–11.

Milestone: a trap or deprivation wipe lands in GAME_OVER (fixing a live gap — today the session stays EXPLORING forever); mode-legality tests for VICTORY.

Design sections: Victory and session end (the mode half only — AdventureCompletedEvent waits for phase 15).

Phase 13 — journal, trigger state, and lifecycle commands

The engine substrate the interpreter will drive, with no interpreter yet: Command.source, session-state blocks for trigger fired-marks and the journal, MarkTriggerFired / AddJournalEntry / RecordNote, their events (TriggerFiredEvent referee-visible, JournalEntryAddedEvent player-visible), the journal in PlayerView, and persistence of the new blocks. Everything here is directly testable by issuing the commands as ordinary referee commands — no trigger matching needed to exercise any of it.

Depends on nothing above (it could run parallel to 10–12); sequencing it fourth just keeps schema churn in one lane at a time.

Milestone: save/load and replay rebuild the journal and fired-marks exactly, with no listeners registered; source survives the command log.

Design sections: The interpreter and the command log (commands and state only), The journal.

Phase 14 — trigger schema and the interpreter

TriggerSpec (event pattern, optional conditions, consequences, repeatable), authored triggers on the adventure document, and the library-shipped Listener: document-order matching, once-only via MarkTriggerFired, cascade depth bounded at 4 with truncation notes, dropped-consequence recording via RecordNote, all consequences before the next player command. validate_adventure grows trigger reference checks (monster, area, dungeon/level, and item ids).

Depends on 11 (condition union) and 13 (lifecycle commands and fired-state).

Milestone: the lever-opens-portcullis scenario authored as data; a golden scenario with the interpreter registered replays identically with no listeners; a trigger spawn colliding with an open encounter drops and records its note.

Design sections: Triggers, the interpreter half of The interpreter and the command log, Visibility.

Phase 15 — quests, victory, and the worked example

QuestSpec (activation, objectives with hidden/reveal, rewards, completion rule, concluding marker), the quest lifecycle commands and session state, the quest events, CompleteQuest → AdventureCompletedEvent + SessionMode.VICTORY, PlayerView active quests, the per-dungeon-level ambient guidance slot, and quest/objective id validation. In the same phase, per the delivery order: examples/tui_crawler registers the interpreter and authors its fetch quest as data, quest.py is deleted, and the osr-forge vocabulary-gap issue is filed as the closing deliverable.

Depends on 12 and 14.

Milestone: the TUI crawler's fetch quest — activation, objective completion matched on the idol's catalog id (no display-name matching), reward, journal beats, victory — runs end to end as authored data and replays clean.

Design sections: Quests, Victory and session end, Delivery order item 1, Forge-backed projects.

Ordering at a glance

The true dependency chain is 10 → 11 → 14 → 15, with 12 and 13 free-floating before their consumers (12 before 15; 13 before 14). Strictly sequential — 10, 11, 12, 13, 14, 15 — is also correct and simplest. If fewer phases are wanted, the natural merge points are 12 into 15 and 13 into 14; going the other way, 15 is the only phase with a defensible internal split (engine-side quest commands versus interpreter wiring plus example conversion), and it likely isn't worth the extra loop.

Rules that keep each phase honest

• Every phase carries its own validate_adventure checks, tests, and CHANGELOG bullet; there is no trailing "validation phase" or "docs phase."
• Nothing bumps SCHEMA_VERSION; each plan PR restates the additive constraint for the specific fields it adds.
• Shared vocabulary (the condition union, the narrative block) is defined at first use and only ever extended additively afterward. A later phase that wants to reshape it has found a spec defect — the move is to stop and reopen the spec, not improvise in the implementation PR.
• Each phase's plan cites the spec sections it implements. If a plan needs to cite this issue for a decision, that decision failed to make it into the spec in step 0 — fix the spec.

Downstream repos

osr-web and osr-editor phases stay in their own repos, filed once phase 15 lands, per the delivery order. osr-web splits naturally into interpreter registration + journal panel + victory screen, then the LLM narration context; osr-editor into regenerated types + ops + the quests panel, then map placement + the lint battery.

[mmacy]

Step 0 is up as #49. One correction to the design surfaced during its rubber-duck review: the content-packs seam claims gates land on "specs that content packs do not carry," but TrapEffect.transition (dungeon.py:257) embeds a TransitionSpec and packs embed traps, so transitions do ride in packs. The spec resolves it with an attempt rule — only commands gate, so requires lives on doors and level-placed transitions, and a trap-effect slide (a forced relocation, not an attempt) never gates — which keeps the pack-safety guarantee intact. Phase 11 planning should work from the spec's formulation, not this issue's.

[mmacy]

As built: the osrlib slice is complete

Delivery-order item 1 shipped end to end. Step 0 — deriving the spec — landed as #49, and the six phases followed the recommended split under the predicted numbering, each through the standard loop of a plan PR and an implementation PR:

Phase	Plan	Implementation	Milestone golden
10 — adventure-bundled items	#50	#51	(validation + catalog tests)
11 — conditions, gates, and narrative blocks	#52	#53	phase11_gates.json
12 — terminal modes	#54	#55	phase12_wipe.json
13 — journal and lifecycle commands	#56	#57	phase13_journal.json
14 — triggers and the interpreter	#58	#59	phase14_triggers.json
15 — quests, victory, and the authored example	#60	#61	phase15_quest.json

Beyond the split, a phase 16 (#62, #63) ran the technical-writer pass that brought the published site into the interpreter era; the authored layer now teaches from its own guide. The phase 15 closing deliverables are done: examples/tui_crawler/quest.py is deleted, the example authors its fetch quest as adventure data and registers the library Interpreter, and mmacy/osr-forge#39 records the overrides-vocabulary gap.

The additive commitment held. SCHEMA_VERSION is 3 because #44 (room traps, before this work) bumped it — nothing in phases 10–16 did, and pre-phase documents and saves load unchanged. All of it is merged to main and sits in [Unreleased]; the last cut release is 1.4.0.

Where what shipped departs from this body

docs/spec.md is the authority for every one of these — each was settled in a plan PR or a review round, never improvised. Recorded here so downstream work (osr-web, osr-editor, osr-forge) reads reality rather than this issue's body:

• The trap-transition correction shipped as the spec formulated it (see the earlier comment): only commands gate, requires lives on doors and level-placed transitions, and a TrapEffect carrying a gated transition is unrepresentable at parse.
• Item collisions are errors, never overrides. This body says "shipped ids win"; the shipped rule is stricter — a bundled id may collide with neither the equipment catalog, the magic-item catalog, nor the rest of the bundle, and a collision fails validate_adventure (and load_game, for doctored saves) with ContentValidationError. One item id names one thing per session; has_item stands on that. The union surfaces as GameSession.effective_equipment, not _effective_items.
• The town shop is a deliberate carve-out. "Everything downstream is existing machinery, unchanged" gained one boundary: PurchaseEquipment stocks the shipped lists only, and a bundled id refuses with items.purchase.not_stocked — the shop must not sell a second copy of the quest idol.
• Trigger consequences address selectors, not character ids. This body never said how an authored GrantItem names a recipient, and session-scoped character ids cannot exist in a document — so a literal character_id is a validation error, and authored commands use @party (every living member, marching order) or @first (the lead survivor), expanded at issue time so the log stays concrete and replays exactly.
• The consequence surface is a typed union, not "referee commands, full stop." ConsequenceCommand closes over the commands a document may author — the grant, flag, spawn, door, place, and time family — and excludes the lifecycle commands (the interpreter's own vocabulary), IdentifyItem (session-scoped instance ids), and RollDice (a draw nothing authored can read). It grows additively, same as the condition union, so the NPC seam survives as written.
• The trigger fired beat is referee-visible. This body lists "fired text for triggers" among the display beats a renderer shows verbatim, which collides with its own ruling that trigger wiring is the game's secret. The more specific ruling won: TriggerFiredEvent and its narrative ride referee visibility, and a trigger's player-facing voice is its journal form.
• Victory's referee legality is narrower than "referee commands remain legal." SpawnMonsters and SpawnNpcParty are illegal in both terminal modes, and PlaceParty is illegal in victory (it stays legal in game_over as the raise-dead salvage door) — a concluded session opens no new play state. Rewards still land after the transition; one that cannot land drops with a note.
• Quests match through clauses, not embedded triggers. Activation and objectives are TriggerClauses — a trigger pattern plus the gate conditions, run by the same matcher triggers use, so the two surfaces cannot drift — while TriggerSpec keeps its flat wire shape. A quest clause with consumes=True is rejected at parse: a quest observes, it does not take. Quest lifecycle beats journal their display text as themselves — the lifecycle event is the beat's event, with no JournalEntryAddedEvent behind it.
• Sharpened semantics, all in the spec: has_item searches every member living or dead (the party carries its dead and their packs) across the whole carried surface, worn slots included; flag equality is strict through flag_values_equal (a stored True never satisfies an authored 1, and an absent key matches nothing); gates check last, after every mundane refusal, so a gate-refused ForceDoor makes no noise and rolls no die; a cascade-truncated once-only trigger is noted, never marked, so it stays fireable; and CompleteQuest on a concluding quest clears any open encounter or battle on its way into victory.
• Fixes the work surfaced, shipped alongside: the non-battle-wipe routing was designed here, but opening the machinery also gave up a rejection-purity violation (refused commands materialized door-overlay entries), a latent GiveItems crash that bundled ids would have made reachable, and a GiveItems/DropItems double-instance raise — all fixed in their phases' PRs.

Deferred exactly as designed

TrapSpec.bypass and condition-keyed prose variants still ride the pack-interaction decision. NPC entities, accept/decline, post-victory play, pack quests, and mid-battle boss triggers remain non-goals. Adventure.hooks is untouched.

What this issue still tracks

Delivery-order items 2 and 3. osr-web's phases (interpreter registration, the journal panel, the victory screen, LLM narration context) and osr-editor's (regenerated types, ops, the quests panel, map placement, the lint battery) file in their own repos, designed against the now-settled schema — osrlib.crawl.gates / triggers / quests / interpreter, schema_version 3, additive since. osr-forge's quest surface is its own repo's decision, recorded at mmacy/osr-forge#39. This issue stays open as the cross-repo anchor until those downstream issues are filed.

[mmacy]

Delivery-order item 2 is filed: mmacy/osr-web#44 is the osr-web anchor, with the spec-derivation PR (mmacy/osr-web#45, specs/authored-layer.md) following the same step-0 discipline this issue's split used — four phases (transcript adoption with interpreter registration, journal/quest UI, victory and gameover endings, narrator context), designed against the as-built record above and the shipped 1.5.0 surface. Item 3 (osr-editor) remains to file.

[mmacy]

Delivery-order item 2 is complete, and item 3 is filed

osr-web shipped all four adoption phases and mmacy/osr-web#44 is closed with its as-built record. The short version for downstream: the floor landed at 1.6.0, not 1.5.0 — phase 2 needed objective display names, so #66 shipped them and 1.6.0 was cut mid-slice (#69) — The Cold Vein is winnable end to end (gate, trigger, quest, journal, victory screen, narrator guidance, all proven against real play), and four engine follow-ups were filed rather than worked around: #67, #68, #70, #71. All four are advisory; none block anything downstream.

Item 3 is anchored at mmacy/osr-editor#60 — the authoring surface, designed against the as-built record above and the shipped 1.6.0 schema. One sequencing note recorded there: the editor's spec meanwhile grew phases 13–14 (the adventure planner, mmacy/osr-editor#58, merged), so the quest-authoring amendment specs as phases 15+ on top of its rewritten quests entry.

That completes what this issue tracks. Item 1 shipped as recorded in the as-built comment above; item 2 is closed as built; item 3 has its anchor; osr-forge's vocabulary gap is recorded at mmacy/osr-forge#39. Per this issue's own rule — it "stays open as the cross-repo anchor until those downstream issues are filed" — the anchors are all filed, and the remaining work tracks in its own repos. Closing as complete.

https://claude.ai/code/session_016Wwh1XWCKHwrqvPL6bhYrt