Skip to main content

Establish a story content layer outside lore truth docs and require story/reveal/branch audits

ADR 0003 — Establish a story content layer outside lore truth docs and require story/reveal/branch audits​

  • Status: Accepted
  • Date: 2026-05-12
  • Deciders: User (project owner)

Context​

The Valenar docs tree now has an explicit lore governance layer under examples/valenar/docs/lore/ plus the migrated per-game design layer under examples/valenar/docs/{systems,acts,generation,ux,catalogs,implementation} and the docs root. ad-0001-lore-prefix-scheme.md and ../pr-file-conventions.md govern the lore-tree prefix and layer rules. ad-0002-lore-docs-migration.md already established that out-of-tree documentation layers can exist without moving gd-* files into docs/lore/.

Wave O introduces a new class of content: story documents, narrative artifacts, and playable-lore documents such as diary entries, letters, reports, inscriptions, ledgers, fragments, scripted scene drafts, and branch-aware story packages. These documents are not the same thing as lore truth sources or game-design truth sources. A story document can depict rumor, omission, bias, limited point of view, propaganda, misunderstanding, or deliberate concealment. Treating story prose as canon by default would collapse the distinction between authored narrative surface and the underlying truth layers that the lore tree is supposed to preserve.

The project also needs a durable agent-review contract for story work. A single writer prompt is not sufficient governance for long-form continuity, reveal pacing, or branch-state tracking. Story content must support future games, future canon-promotion decisions, and multiple agent styles without letting narrative drafts silently mutate canon.

Decision​

Establish examples/valenar/docs/story/ as the dedicated story content layer for Valenar. This layer sits outside examples/valenar/docs/lore/ and outside the gd-* design tree. Story documents live in examples/valenar/docs/story/; lore truth remains in ul-*, gl-*, ud-*, and lh-*; game-design truth remains in gd-* and related process docs.

Story prose is not canon by default. A story document may portray events, beliefs, testimony, or discoverable text, but it does not become canon truth merely by existing in the story layer. Any canon change, reveal authorization, or rules/mechanics change must be explicit. Story-layer acceptance therefore distinguishes between:

  • the playable or readable narrative artifact itself;
  • any proposed canon delta surfaced by that artifact; and
  • the actual truth-layer update, which must be recorded explicitly in the appropriate lore/design files rather than inferred from prose.

No new two-letter lore prefix is introduced for story documents in this ADR. The prefix scheme in pr-file-conventions.md remains the source of truth for the lore tree and gd-* design files. Story documents are a separate layer, not an exception inside the lore tree. A future ADR may introduce a dedicated story-prefix scheme if the story layer grows large enough to justify one, but this ADR does not do so.

gd-* files do not move into docs/lore/, and existing gd-* files are not renamed or relocated as part of this decision.

Wave U alignment outcome​

Wave U's universe-lore alignment pass found no contradiction requiring edits to the existing universe-lore, universe-design, or hook authorities. The correct Wave U outcome for this ADR is therefore no edit on the authority set: the committed ul-*, ud-*, and lh-* files remain unchanged, and story-layer governance aligns to them rather than rewriting them.

Wave U's wave-owned documentation outcome is limited to this ADR file. Unrelated pre-existing working-tree edits in ul-*, ud-*, lh-*, gl-*, or UX files remain out of scope for this wave and do not change the no-edit authority result recorded here.

For future story-layer work, the authority surfaces are:

  • examples/valenar/docs/lore/universe/ul-cosmology.md
  • examples/valenar/docs/lore/universe/ul-divine-layer.md
  • examples/valenar/docs/lore/universe/ul-shroud.md
  • examples/valenar/docs/lore/universe/ul-demon-cycle.md
  • examples/valenar/docs/lore/universe/ul-demon-cosmology.md
  • examples/valenar/docs/lore/universe/ul-demon-king-remains.md
  • examples/valenar/docs/lore/universe/ul-wardhearts-and-nexuses.md
  • examples/valenar/docs/lore/universe/ul-hero-calling.md
  • examples/valenar/docs/lore/universe/ud-world-law.md
  • examples/valenar/docs/lore/hooks/lh-game1-cosmology-hooks.md
  • examples/valenar/docs/lore/hooks/lh-game1-world-hooks.md

Future story README files, frontmatter templates, audit checklists, subagent prompts, or validators must cite those authority files directly for canon truth and exposure-tier control instead of restating their contents in story-layer governance prose.

Wave U also identified three Game 1 audit hazards that future story/reveal work must treat as caution surfaces rather than canon-promotion targets:

  • examples/valenar/docs/lore/local/gl-game1-demon-remains.md mixes accepted local facts with deferred/proposed remains terminology and dangerous vision surfaces.
  • examples/valenar/docs/lore/local/gl-game1-old-hero-traces.md contains deferred naming and referenced once / hinted exposure ceilings that are easy to overstate in story prose.
  • examples/valenar/docs/lore/local/gl-game1-false-king.md depends on deliberate late-game political reveal timing and must not be surfaced above the allowed tier in early story artifacts.

Required frontmatter for story documents​

Every accepted story document under examples/valenar/docs/story/ must carry YAML frontmatter using the committed reusable template at examples/valenar/docs/story/templates/story-entry-template.md. The deterministic parts of that contract are now enforced by the committed validator automation documented in examples/valenar/docs/story/README.md, examples/valenar/docs/implementation/pr-llm-story-authoring-pipeline.md, and tools/README.md, but the accepted document must at minimum declare:

  • a story-document identity (title and artifact classification);
  • document status;
  • source-of-truth references to the lore/design files the document depends on;
  • an explicit canon-delta declaration, including when the answer is "none";
  • reveal scope, stating what the document is allowed to expose and at what level;
  • branch scope, stating whether the document is linear or branch-sensitive and where branch consequences are tracked.

If a document cannot declare those items clearly, it is not ready for acceptance into the story layer.

Required audits before acceptance​

Every story document requires three distinct audits before it is accepted.

1. Story audit​

The story audit checks the narrative artifact itself: internal coherence, voice consistency, readable structure, declared artifact type, and alignment with the cited lore/design sources. It rejects documents that silently invent canon, present conjecture as truth without labeling it, or depend on unstated background facts.

2. Reveal audit​

The reveal audit checks exposure control. It verifies that the document's stated reveal scope matches the cited ul-*, gl-*, ud-*, and lh-* sources, and that it does not surface bible-only or over-tier material. A story document may hint at truth, obscure truth, or contradict an in-world narrator, but the audit must confirm that the document does not exceed the allowed exposure tier for the game.

3. Branch audit​

The branch audit checks branch/state discipline. If a story document is branch-sensitive, it must identify the branch boundary, the intended consequences, and the ledger or follow-up surface where those consequences are tracked. No branch-dependent outcome may be left implicit. If the document is linear, the frontmatter must say so explicitly.

Passing all three audits is required for acceptance. The committed structural validator plus the committed read-only story-role layer described in examples/valenar/docs/implementation/pr-llm-story-authoring-pipeline.md now provide reusable scaffolding for that review, but prose quality, nuanced reveal interpretation, and branch judgment still require explicit audit reasoning rather than inference from prose alone.

Rationale​

  • Narrative surface is not truth storage. Story documents need room for unreliable narrators, partial witnesses, propaganda, ritual language, and incomplete discovery. Keeping them outside the lore truth layers preserves that distinction.
  • Explicit canon promotion avoids silent drift. When canon changes are recorded explicitly in ul-*, gl-*, ud-*, lh-*, or gd-*, reviewers can see the delta directly instead of reverse-engineering it from prose.
  • The existing convention already supports out-of-tree layers. ad-0002-lore-docs-migration.md established that gd-* remains outside docs/lore/. Adding a story layer outside the lore tree follows that same separation model rather than contradicting it.
  • Audit separation prevents one prompt from doing everything badly. Story quality, reveal discipline, and branch/state correctness are different review problems. Distinct audits keep those concerns legible and make future agent specialization possible.
  • Future games need the same boundary. A later game may create its own examples/<game>/docs/story/ layer without inheriting Valenar's specific story files. The structure generalizes without forcing cross-game canon into narrative drafts.

Alternatives considered and rejected​

  • Store story prose inside docs/lore/. Rejected. Doing so would blur the line between narrative artifact and truth-layer canon, and would incorrectly subject story files to lore-tree prefix expectations.
  • Treat every accepted story document as canon by default. Rejected. Story documents can contain rumor, bias, concealment, and staged revelation. Canon must remain explicit.
  • Create a generic writer agent that both authors story and updates canon silently. Rejected. Story writing and canon promotion are separate responsibilities with separate review burdens.
  • Introduce a new story prefix immediately. Rejected for Wave O. The current problem is layer definition and audit governance, not filename signaling within a populated story tree.
  • Move existing gd-* files into docs/lore/ so story, lore, and design sit together. Rejected. ad-0002-lore-docs-migration.md already decided the opposite boundary, and this ADR preserves it.

Consequences​

  • Future Valenar story documents live under examples/valenar/docs/story/ and require frontmatter plus story/reveal/branch audits before acceptance.
  • Lore truth remains authored in examples/valenar/docs/lore/; design truth remains authored in the existing gd-* and process layers. Story documents may cite those files but do not replace them.
  • Wave U's universe-lore result is an audit/alignment pass, not a canon rewrite. No ul-*, ud-*, or lh-* file changes are authorized or implied by this ADR.
  • Canon promotion from a story document requires an explicit follow-up update to the target truth-layer docs. No reviewer may infer canon truth from prose alone.
  • No change to examples/valenar/docs/lore/pr-file-conventions.md was required for this ADR because that file is already scoped to the lore tree rather than every file under examples/valenar/docs/.
  • Future games may adopt their own examples/<game>/docs/story/ layer with the same non-canon-by-default rule and audit requirement.

Explicit deferrals​

  • A dedicated write-specialized story-author workflow and broader format-specific authoring coverage beyond the currently committed diary-entry path remain future work.
  • Richer prose-quality review, nuanced reveal/branch judgment, and canon-promotion merit review remain future work beyond the committed deterministic validator and read-only story-role layer.
  • Any future additions beyond the committed template, validator, and read-only story-role layer must preserve Wave U's no-edit authority outcome by citing the existing ul-*, ud-*, and lh-* authority files directly and by carrying forward the Game 1 caution surfaces named in gl-game1-demon-remains.md, gl-game1-old-hero-traces.md, and gl-game1-false-king.md.

References​

  • pr-file-conventions.md (same directory) — the living governance document for the lore-tree prefix scheme and layer rules.
  • ad-0001-lore-prefix-scheme.md (same directory) — adopted the lore-tree prefix scheme.
  • ad-0002-lore-docs-migration.md (same directory) — established that gd-* remains outside docs/lore/ and that out-of-tree documentation layers are valid when explicitly governed.
  • hooks/lh-game1-cosmology-hooks.md and hooks/lh-game1-world-hooks.md — exposure-tier authorities story reveal audits must cite instead of restating.
  • local/gl-game1-demon-remains.md, local/gl-game1-old-hero-traces.md, and local/gl-game1-false-king.md — current Game 1 caution surfaces for story/reveal audit follow-up.