Trailer Vocabulary

Complete Trailer Table

Trailer	Required	Semantics
Lore-id:	Auto-generated	Stable atom identity (8-char hex)
Constraint:	No	Rules that shaped this decision and may still be active
Rejected:	No	Alternatives evaluated and dismissed. Format: alternative | reason
Confidence:	No	Author’s assessment: low, medium, high
Scope-risk:	No	Blast radius: narrow, moderate, wide
Reversibility:	No	clean, migration-needed, irreversible
Directive:	No	Forward-looking instructions for future modifiers
Tested:	No	What was verified and how
Not-tested:	No	What was not verified and why
Supersedes:	No	Lore-id of atom this decision replaces
Depends-on:	No	Lore-id of atom this decision requires
Related:	No	Lore-id of atom with a general relationship

Enum Semantics

Confidence

Value	Meaning
low	Hypothesis or first attempt. No verification performed. “I believe this is correct but haven’t confirmed.”
medium	Locally verified or based on documentation. Tested in development but not production-like environments.
high	Thoroughly tested (CI, staging, or production). Based on extensive domain knowledge or verified against requirements.

Scope-risk

Value	Meaning
narrow	Isolated to a single function, component, or file. No external callers affected.
moderate	Affects a module or has known consumers. Blast radius is bounded and enumerable.
wide	Affects cross-cutting concerns, public APIs, data schemas, or shared infrastructure. Callers may be unbounded or unknown.

Reversibility

Value	Meaning
clean	Can be reverted with git revert. No side effects beyond source code.
migration-needed	Revert requires a data migration, config change, infrastructure update, or external coordination.
irreversible	Cannot be fully undone: data deletion, published artifacts, external API calls, or contractual/compliance changes.

Constraint Lifecycle

Constraints are immutable within their commit (per git’s design). Lifecycle is managed through the Supersedes: mechanism:

1. Commit A introduces Constraint: Auth service does not support introspection with Lore-id: a1b2c3d4
2. Six months later, commit B adds introspection support. Its trailers include Supersedes: a1b2c3d4
3. lore constraints src/auth/ now filters out commit A’s constraint by default

No mutation needed. The append-only log is preserved. Lifecycle is achieved through chaining, not editing.

Partial Supersession

If commit A had 3 constraints and only 1 is obsolete, commit B can supersede the entire atom and carry forward the still-valid constraints:

Supersedes: a1b2c3d4
Constraint: Auth service rate-limits introspection to 10 req/s
Constraint: Must not add latency to non-expired-token paths

Supersession is at the atom level, not the individual trailer level.

Directive Lifecycle

Directives support an optional inline expiry hint:

Directive: [until:auth-v3] Do not narrow error handling without verifying upstream
Directive: [until:2026-06] Maintain Python 3.8 compatibility
Directive: Error handling is intentionally broad (all 4xx)

• The [until:...] prefix is optional metadata, not enforced by the protocol
• lore stale parses [until:...] hints and flags directives whose condition appears met
• A directive without [until:...] is permanent until superseded
• Directives can also be retired via the Supersedes: mechanism