Skip to main content

ADR 0004 - Place Valenar lore ADRs under lore/adr/

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

Context​

The Valenar lore tree already has multiple accepted ADRs. Keeping those ad-* files beside pr-file-conventions.md and the lore content directories made the sidebar read as a flat mixture of governance, canon, hooks, and local lore. The docs portal now exposes the ADRs as a nested group under the file conventions page, and the source tree should match that mental model.

pr-file-conventions.md previously allowed ad-* and pr-* files at the lore/ root unless an ADR explicitly created a subfolder. This ADR creates that subfolder for lore-tree ADRs.

Decision​

Create examples/valenar/docs/lore/adr/ as the physical home for Valenar lore-tree ADRs. Move existing lore ADRs into that folder and keep future ad-* files there.

pr-* files remain at examples/valenar/docs/lore/ root unless a future ADR creates a separate process/governance folder. The current root convention file stays at examples/valenar/docs/lore/pr-file-conventions.md.

Consequences​

  • Lore ADR paths use examples/valenar/docs/lore/adr/ad-NNNN-*.md.
  • Links from implementation docs and agent rules must cite the new adr/ path.
  • The docs portal sidebar nests the ADR folder beneath Lore / Design File Conventions.
  • The lore ADR namespace remains separate from workspace-root docs/decisions/; this change only moves the Valenar lore ADR files into a dedicated folder.

Alternatives considered​

  • Keep ADRs at lore/ root. Rejected. It preserves the old convention but keeps the source tree and sidebar noisier than necessary.
  • Move all governance files under lore/adr/. Rejected. pr-file-conventions.md is a convention/process document, not an ADR, and it remains the root entry point for the lore-tree rules.