Protocol Fundamentals

Protocol Version

Every Lore-enabled repository has a .lore/config.toml that declares the protocol version:

[protocol]
version = "1.0"

Compatibility rules:

• Unknown trailers are always preserved (forward compatibility)
• Deprecated trailers from older versions are accepted but flagged as warnings (backward compatibility)
• The CLI refuses to operate if the config version is newer than the CLI supports, and prints an upgrade message
• No Lore-version: trailer in commits — the version lives in config, not in every message

Lore Atoms

A Lore atom is a single Lore-enriched commit. Each atom represents one decision unit. The term “atom” emphasizes that decisions should be small and focused — if a commit needs more than 5 constraints or 5 rejected alternatives, it’s likely too large and should be split.

Lore-id: Stable Identity

Each atom carries a stable identity that survives rebase:

Lore-id: a7f3b2c1

• 8-character random hex, generated automatically by lore commit
• Stored as a trailer in the commit message — survives rebase because message content is preserved
• All cross-references use Lore-id values, not commit hashes
• Collision risk is negligible: 4 billion possible values

Why not commit hashes? Commit hashes change on rebase and cherry-pick. Since rebase is the most common operation that would break cross-references, Lore-ids use a message-embedded identity instead.

Relationships

Atoms can reference each other using three typed relationship trailers:

Trailer	Meaning
Supersedes: <lore-id>	This decision explicitly replaces a previous one
Depends-on: <lore-id>	This decision requires another to be in effect
Related: <lore-id>	General association (doesn’t fit supersedes/depends-on)

These replace the paper’s original flat Related: trailer, which had no relationship semantics.

Impact on queries: lore constraints automatically filters out constraints from atoms that have been superseded. Use --all to see the full history.