Skip to main content

ADR 0002 — Migrate existing Valenar game-design docs to gd-* and pr-* prefix scheme

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

Context​

Wave 0 Q2 authorized the migration of the existing examples/valenar/docs/{systems,acts,generation,ux,catalogs,implementation} files to the prefix scheme adopted in ad-0001-lore-prefix-scheme.md and defined in ../pr-file-conventions.md. Wave D is the deliberate sweep ad-0001 deferred for future migration. This ADR records the authorization, the precise scope, and the consequences of that sweep.

An earlier revision of pr-file-conventions.md explicitly deferred the question of where gd-* files physically live within the repository. This ADR resolves that historical deferral.

Resolution of the gd-* placement deferral. gd-* files remain in their existing subdirectories — examples/valenar/docs/systems/, examples/valenar/docs/acts/, examples/valenar/docs/generation/, examples/valenar/docs/ux/, examples/valenar/docs/catalogs/, and examples/valenar/docs/ (root for gd-canon.md and gd-glossary.md). They do not move under examples/valenar/docs/lore/. The docs/lore/ subtree remains exclusively for lore-layer files: ul-* (universe lore), gl-* (game-local lore), lh-* (lore hooks), ud-* (universe design), ad-* (architecture decision records), and pr-* (project / process / meta) within the lore tree. gd-* (game design) lives in the flat per-game design layer at examples/valenar/docs/, not in the lore tree.

Rationale for the placement decision: the lore/ subtree exists for cross-layer and universe-scope content that is shared across games (the universe/ subtree is referenced by reference, not duplicated, when a future game is added). gd-* content is per-game game-design and belongs in the per-game design layer alongside the rest of that game's docs. Mixing gd-* files into docs/lore/ would conflate per-game game design with universe/cross-game content and would force readers to look in docs/lore/ for files that are not lore. Keeping gd-* in the existing folder structure preserves the team's mental model while adding the layer signal at every reference site.

Decision​

Wave D performs the following migration:

  • Rename every file under examples/valenar/docs/{systems,acts,generation,ux,catalogs}/ to add a gd- prefix in place. The 48 files keep their parent directory; only the filename gains the prefix.
  • Rename every file under examples/valenar/docs/implementation/ to add a pr- prefix in place. The 7 files keep their parent directory; only the filename gains the prefix. None of those files are game design — they are all process, governance, drift-tracking, and meta documents.
  • Rename examples/valenar/docs/current-ux/SCREENSHOTS_REFRESH.md to examples/valenar/docs/current-ux/pr-screenshots-refresh.md. The rename also lowercases and hyphenates the name to conform to the lowercase-hyphenated naming convention. The screenshot PNG files and stage-0-mockups/ HTML in current-ux/ are binary/non-md assets and are not in scope.
  • Rename examples/valenar/docs/canon.md to examples/valenar/docs/gd-canon.md. The file stays at the docs/ root.
  • Rename examples/valenar/docs/glossary.md to examples/valenar/docs/gd-glossary.md. The file stays at the docs/ root.
  • Leave examples/valenar/docs/README.md unprefixed. README.md is a directory navigation index, not game-design content. Renaming it would break the GitHub directory auto-display convention with no compensating gain. Its internal links are updated to use the new gd-* and pr-* paths.

Total files renamed by Wave D: 56. Total files updated for inbound references: every file containing a Markdown link, a CLAUDE.md path reference, a script-resident path, a comment-only path citation, or a workspace-doc prose mention pointing at a renamed file.

The migration is performed atomically in a single logical commit. There are no redirect stubs, no "see also old path" files, and no backwards-compatibility aliases. Git history preserves the historical name under the new path through git mv.

Rationale​

  • Layer signaling at every reference site. A prefix-visible filename prevents accidental layer-crossing references and surfaces the layer of every file in directory listings and grep results without opening the file.
  • In-place rename preserves organization. Subdirectory groupings (systems/, acts/, generation/, ux/, catalogs/, implementation/) already encode topical grouping; the prefix is layer-orthogonal to that grouping. Keeping files in place preserves the team's existing mental model while adding the layer signal.
  • Atomic migration eliminates a half-state. Mixing pre-migration and post-migration filenames would force every consumer to know which files have been migrated. A single atomic sweep avoids that ambiguity.
  • Future-game compatibility. A second game in this setting has its own examples/<game>/docs/ tree with its own gd-* files. The shared universe lore at examples/valenar/docs/lore/universe/ is referenced by both games. The migration leaves that boundary intact.
  • No redirect stubs. Block B forbidden patterns and project-wide tenets prohibit "see also new path" stubs. Git history is the legacy record; there is no need for the live filesystem to carry a redirect.

Alternatives considered and rejected​

  • Per-folder prefix only, no file rename. Rejected by the user in Wave 0. Folder names alone do not put the layer signal on every reference site; a prefix on every filename does.
  • Move gd-* files into docs/lore/gd/. Rejected. gd-* files are not lore. Mixing them into the lore tree would conflate per-game game design with universe/cross-game content. The lore tree stays exclusively for lore-layer files.
  • No migration; defer indefinitely. Rejected by the user in Wave 0 Q2. The longer the prefix scheme runs alongside an unprefixed legacy tree, the more new files inherit the inconsistency.
  • Redirect stubs at old paths. Rejected. Block B forbidden patterns and the project's no-backwards-compatibility tenet rule them out.
  • Rename README.md to pr-README.md. Rejected. GitHub's directory auto-display convention is a real UX feature; the cost of losing it is concrete and the gain (uniform prefix coverage) is symbolic.
  • Migrate only the user-named subfolders (systems/acts/generation/ux/) and leave catalogs/, implementation/, gd-canon.md, gd-glossary.md, and current-ux/ alone. Rejected. The user explicitly authorized the full atomic update during Wave D dispatch. A partial migration leaves a half-state where some files have layer signals and adjacent files do not.

Consequences​

  • All Markdown links in examples/valenar/docs/** are updated atomically to use the new gd-* and pr-* paths.
  • scripts/check-behavior-vocabulary.sh GROUP_C_EXEMPT_FILES and the corresponding echo string are updated to point at examples/valenar/docs/implementation/pr-docs-codegen-rules.md. Without this update the CI guard would lose its exemption for that file and emit false-positive Group C violations.
  • Comment-only doc citations in examples/valenar/Content/locations/scopes.secs, examples/valenar/Content/locations/sites/scopes.secs, examples/valenar/Generated/Hashes.cs, and examples/valenar/Generated/Locations/LocationKnowledgeTypes.cs are updated to point at the new gd-* paths. Provenance headers and the no-source stand-in marker in Generated/ are not touched.
  • examples/valenar/CLAUDE.md path references are updated to the new gd-* paths.
  • Workspace-level prose references in docs/decisions/ADR-0002-behavior-vocabulary.md, docs/RECOVERY_WAVES.md, docs/design/FUTURE_WORK.md, and docs/design/08-collections-and-propagation.md are updated to the new gd-* and pr-* paths.
  • The earlier pr-file-conventions.md deferral of gd-* placement is resolved by this ADR. Future authors who need to add gd-* files have a committed rule: they live in the per-game flat design layer at examples/<game>/docs/{systems,acts,generation,ux,catalogs}/ (or at the docs/ root for gd-canon.md / gd-glossary.md), not in docs/lore/.
  • A later follow-through wave may insert lh-* cross-reference link annotations into specific sections of the renamed gd-* files. This ADR does not schedule or name that follow-through; it only records the migration boundary.
  • pr-file-conventions.md now reflects the resolved gd-* placement boundary directly and points non-lore quest-owner and navigation placement at ../../pr-quest-owner-and-navigation-model.md and ad-0005-owner-pages-and-navigation-views.md. The old future conventions follow-through is closed.

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. Its earlier gd-* placement deferral is the historical deferral resolved by this ADR, and the current file now reflects the resolved boundary directly.
  • ad-0001-lore-prefix-scheme.md (same directory) — the ADR that adopted the prefix scheme for examples/valenar/docs/lore/ and explicitly deferred migration of the existing acts/, systems/, generation/, ux/, catalogs/, and implementation/ files to a future Wave D.
  • examples/valenar/docs/README.md — the directory index, retained without a prefix because it is a navigation index, not game-design content.