Project-File Conventions (pr-)

This document is the master workspace-root convention for naming, foldering, prefixing, and cross-referencing documentation files committed under docs/** and the per-game documentation trees (such as examples/valenar/docs/lore/). The path-scoped rule at .claude/rules/docs-conventions.md summarises the prefix table for the auto-loader; this file holds the full rationale, deviation list, and operational rules.

Purpose

mapv10, Valenar, SECS engine work, and the cross-cutting language design tree all write Markdown into the same docs/ namespace at the workspace root. Two classes of collision happen without a convention:

• Flatten collisions. docs/archive/03-stats-and-modifiers.md and docs/design/03-stats-and-modifiers.md carry the same leaf name and only the parent directory disambiguates them. A reader following a leaf-name reference (or a tool that resolves by basename) cannot tell which one was meant.
• Mirror collisions. docs/design/behavior-vocabulary.md (in-repo reference) and .claude/rules/behavior-vocabulary.md (auto-loaded governance) document the same vocabulary on two surfaces, and edits drift between them.

The two-letter prefix scheme below makes leaf names globally unique within the workspace-root docs/ tree and assigns each file to a layer with predictable cross-reference rules.

Prefix table

The table is closed. Introducing a new prefix requires an ADR (docs/adr/ad-NNNN-add-<prefix>-prefix.md).

Prefix	Layer	Folder
ul-	Universe lore	docs/lore/universe/
gl-	Game-local lore	docs/lore/games/{game}/
lh-	Lore hooks / cross-reference	docs/lore/games/{game}/hooks/
gd-	Game design	docs/design/games/{game}/
ud-	Universe design	docs/design/universe/
ad-	ADRs	docs/adr/
sp-	Specs	docs/specs/
rn-	Runtime / engine	docs/runtime/
pr-	Project / process / meta	docs/project/

Each row's folder is also closed: a ul-* file may not live under docs/design/, a gd-* file may not live under docs/lore/, and so on.

Rules for new files

• Every new file under docs/** must carry a valid prefix from the table above.
• Post-prefix names must be globally unique within the workspace-root docs/ tree. Lowercase-hyphenated, no spaces, no underscores. Example: docs/project/pr-file-conventions.md, not docs/project/PR File Conventions.md.
• New files declare layer membership in YAML frontmatter:
  • prefix: — the two-letter prefix (e.g. pr-).
  • layer: — a short layer tag (project-process, runtime-architecture, game-design, etc.).
  • status: — proposed / accepted / superseded.
  • date: — ISO date (YYYY-MM-DD).
  • ad-* files add id: (AD-NNNN) and title:.
• The prefix scheme is a naming convention, not an access control mechanism. Tools and agents still load files by path.

Rules for existing files (no silent migration)

Existing un-prefixed files under docs/decisions/, docs/design/, docs/research/, docs/archive/, and the top-level docs/*.md files keep their names. This convention does not retroactively rename anything. Migration is the explicit scope of a future Project-File-Migration-Prompt.md task — it does not happen as a side effect of an unrelated wave.

No silent renames. No redirect stubs. Mixing prefixed and un-prefixed files in the same tree is expected during the transition window. When editing an existing un-prefixed file, leave the name alone and edit in place. When editing a prefixed file, read its YAML frontmatter first to know which layer's cross-reference rules apply.

Cross-layer reference rules

The prefix tells the reader which layer the file belongs to, and layer membership restricts what it is allowed to reference:

• ul-* (universe lore) and ud-* (universe design) may reference only other ul-* / ud-* files. They are game-agnostic; referencing a gl-* or gd-* file would couple universe-level content to a specific game.
• gl-* (game-local lore) may reference same-game gl-* files plus any ul-* / ud-* files. It may not reference other games' gl-* files.
• gd-* (game design) routes any lore references through lh-* (lore hooks). gd-* does not reach directly into gl-* / ul-*.
• lh-* is the only mediation layer between design and lore. Every lh-* file has an exposure plan rule (see below) so a hook does not silently leak universe-level lore into a game-design surface.
• sp-* (specs) and rn-* (runtime) may reference each other and any ad-* / pr-* files. They do not reference lore.
• pr-* (project/process) may reference anything; it is the meta layer.

A ul-* or ud-* file referencing a gl-* file is a layering FAIL and must be caught by review.

Canonicity tier rule (for ul-* files)

Universe-lore files carry an explicit canonicity tier in YAML frontmatter when the layer is universe-lore:

canonicity: hard      # immutable universe truth
canonicity: soft      # mutable, may be re-canonised
canonicity: hypothesis  # exploratory, not yet adopted

hard lore may not be contradicted by soft or hypothesis lore. soft lore may be elevated to hard only through an explicit ADR.

Exposure plan rule (for lh-* entries)

Every lh-* file describes a single mediation hook and must answer in its frontmatter or first body paragraph:

• What lore it surfaces (cite the specific ul-* / gl-* file).
• Which design surface it surfaces it on (cite the specific gd-* file or game subsystem).
• What the player sees (in-game label, tooltip, name, codex entry, etc.).
• What the player does not see (canonicity-hard details that stay hidden by design).

Without an exposure plan, a hook is not a mediator; it is a leak.

Repo-specific deviations

The workspace root pre-dates this convention. Several deviations remain permanently or until an explicit migration:

• docs/decisions/ADR-NNNN-*.md (uppercase, legacy) and docs/adr/ad-NNNN-*.md (lowercase, new) are two separate workspace-root ADR namespaces. Cite the full path or name the subject; a bare ADR-0002 reference is ambiguous.
• docs/design/ retains its existing numbered specs (00-overview.md through 10-host-secs-execution-boundary.md) under their current un-prefixed names. NEW spec content goes into docs/specs/ with the sp- prefix; numbered design specs stay where they are.
• docs/research/ continues as the un-prefixed scratch tier; docs/project/pr-* is committed governance. Research notes do not graduate to governance by simple rename — they require an ADR or a promotion task.
• docs/archive/ holds the prior numbered spec (01-core-model.md through 12-on-actions-and-actions.md, plus secs-language.md) under its original names. The archive is read-only governance for legacy semantics; new files do not land there.
• Workspace-root top-level files (CLAUDE.md, AGENTS.md, README.md, TASKS.md, WORLD_STRUCTURE_DESIGN.md, SECS-Compiler-Plan.md, etc.) sit outside docs/ and outside this prefix scheme by design — they are workspace-root governance.
• Spaces in filenames. Some historical files used spaces; new files must not.

ADR namespace rule

Two ADR namespaces co-exist:

• docs/decisions/ADR-NNNN-*.md — legacy uppercase namespace.
• docs/adr/ad-NNNN-*.md — new lowercase namespace following this convention.

New ADRs go to docs/adr/ with the ad- prefix and a four-digit id. Cross-references must cite the full path; a bare ADR-0002 is ambiguous because both namespaces use four-digit ids.

Per-game tree specializations

Per-game documentation trees extend this convention with a game-local copy. The Valenar tree, for example, owns its own conventions doc at examples/valenar/docs/lore/pr-file-conventions.md covering Valenar's local prefix usage (the gl-, lh-, gd- layers it owns) and any Valenar-specific deviations. Game-local conventions documents inherit this workspace-root master and document only the deltas — they do not re-define the global prefix table.

When to migrate

A future Project-File-Migration-Prompt.md task may sweep un-prefixed docs into the new scheme. Until that task runs:

• Do not rename existing files.
• Do not introduce redirect stubs.
• Do not retroactively apply cross-layer rules to un-prefixed files.

When the migration runs, it will:

1. Move each in-scope file to its canonical folder.
2. Apply the prefix.
3. Backfill the YAML frontmatter.
4. Update inbound references in the same commit.
5. Leave research/archive trees in place unless the ADR for the migration explicitly opts them in.

This convention is the contract the migration will follow. Edits to the prefix table or the deviation list before the migration require an ADR.