Skip to main content

ADR 0001 — Adopt two-letter prefix scheme for lore/design docs under examples/valenar/docs/lore/

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

Context​

Wave U initiates universe-lore authoring for the Valenar setting. Up to this point the existing docs/ tree at examples/valenar/docs/ has used folder-by-purpose organization (acts/, systems/, generation/, ux/, catalogs/, implementation/) without any explicit layer-signaling prefix on filenames. As the project begins adding universe lore, game-local lore, cross-reference hooks, and cross-game design documents, flat folder names become ambiguous about which layer a file belongs to and which references between files are legal. A reader following a Markdown link from one file to another has no visual cue, in the filename alone, of whether they are crossing a layer boundary.

A prefix scheme on filenames solves layer signaling without requiring deep nesting. With a prefix, layer membership is visible at every reference site, every directory listing, and every cross-link; the reader does not need to open a file to know whether it is universe canon, game-local canon, a hook table, or a design document.

Decision​

Adopt the two-letter prefix table defined in ../pr-file-conventions.md for all new files created under examples/valenar/docs/lore/. The prefixes are: ul- (universe lore), gl- (game-local lore), lh- (lore hooks), gd- (game design), ud- (universe design), ad- (architecture decision records), sp- (specs), rn- (runtime), pr- (project / process / meta). The prefix and subdirectory must agree, post-prefix names are globally unique within the lore tree, and cross-layer reference rules are enforced as defined in the conventions file.

The existing files under examples/valenar/docs/ that sit outside docs/lore/ are not renamed by this ADR. Their migration to the prefix scheme is deferred to a future Wave D, governed by a separate Project-File-Migration-Prompt.

Rationale​

  • Layer signaling at every reference site. A prefix-visible filename prevents accidental ul- to gl- reference violations even when reading filenames alone, because the prefix is visible in every Markdown link, every directory listing, and every grep result. The convention is enforced by the eye, not only by validation tooling.
  • Prefix invariant under refactoring. A file's prefix encodes its layer; moving it within the lore tree does not change its layer. Future restructuring of subfolders does not require touching cross-references.
  • Future-game compatibility. Future games in this setting can have their own gl-* trees under their own examples/<game>/docs/lore/local/ folders without polluting the shared ul-* tree. The same ul-* files are referenced by every game's lh-* tables. A two-game future is built into the convention from day one.
  • ADR-first commit order. The convention file (pr-file-conventions.md) and this ADR are committed before any other file uses them. This prevents drift between the convention and the first files written against it. Subsequent waves inherit a stable rule set rather than racing the rule set into existence alongside content.
  • Conservative authoring discipline. Canonicity tiers (hard canon, soft canon, proposed, bible-only) and exposure tiers (revealed, hinted, referenced once, hidden) are defined together with the prefix scheme so that authoring discipline is not split across multiple governance documents. A reader of pr-file-conventions.md learns both the layout rules and the reveal discipline in one place.

Alternatives considered and rejected​

  • No prefix, folder-only organization. Rejected. Folder names alone do not prevent reference-direction errors. A reader opening a Markdown cross-reference link has no visual cue in the link text about which layer they are reading. The cost of typing two extra characters per filename is far smaller than the cost of a ul- to gl- layering violation slipping through review.
  • Per-folder implicit layer. Rejected. Implicit layer-by-folder requires the reader to know which folder a file is in before they can interpret its content. Cross-references in particular lose their layer signal — a link to wardhearts.md does not say whether it lands in universe/ or local/. A prefix on the filename keeps the layer signal attached to every reference.
  • Full repo-root migration (Option A from the Wave 0 placement decision). Rejected by the project owner during Wave 0. Lore for this game lives at examples/valenar/docs/lore/, not at docs/lore/ at the workspace root. This keeps game-specific content co-located with the game implementation and keeps the workspace root reserved for engine-wide documents. A future game adopts the same examples/<game>/docs/lore/ pattern under its own example tree.
  • Prefix on existing files immediately, in this wave. Rejected. Migrating existing files in examples/valenar/docs/{systems,acts,generation,ux,catalogs,implementation} to the new scheme would entangle Wave U's authoring work with a separate migration sweep. It would also force decisions about each existing file's correct prefix without a deliberate review. Migration is deferred to a future Wave D so the prefix scheme is committed cleanly first and the migration is its own deliberate operation.
  • Three-letter or longer prefixes. Rejected. Two letters carry enough layer information for the current set of layers and remain visually compact in directory listings and cross-references. Adding length without information cost is a future-extensibility cost paid for no current benefit.

Consequences​

  • A future Wave D must migrate existing acts/, systems/, generation/, ux/, catalogs/, and implementation/ files to the appropriate prefix (most likely gd-*, since they describe game design rather than universe lore). That wave begins only when a Project-File-Migration-Prompt is issued.
  • Future games in this setting inherit the convention. A second game would create its own examples/<game>/docs/lore/ tree with local/ and hooks/ subfolders, and reference the existing examples/valenar/docs/lore/universe/ul-*.md files for cross-game canon. The universe/ tree is shared by reference, not duplicated.
  • The pr-file-conventions.md file is the living governance document; this ADR records the decision but does not duplicate the rules. The two must remain consistent — if a rule changes, the conventions file is updated and a follow-up ADR records the rationale.
  • The ud-* prefix co-locates inside lore/universe/ because universe design (cross-game mechanics such as the True Harm rule) is conceptually adjacent to universe lore. Both are authored against cross-game scope; both are referenced by every game's lh-* and gd-* documents.
  • Cosmological reveal discipline (the Game 1 ceiling rule) is encoded in the conventions file rather than this ADR so that the discipline applies to every future game by default. Future games may carry their own ceiling rules, but the discipline structure is shared.

References​

  • pr-file-conventions.md (same directory) — the living governance document defining the prefix table, cross-layer reference rules, canonicity tiers, exposure tiers, and the Game 1 reveal-tier ceiling rule.