lore-commits（传说提交）

Lore Commits

Overview

Every commit destroys decision context. You considered alternatives, evaluated tradeoffs, and chose one approach — but only the final diff survives. Lore reclaims this lost knowledge by encoding it as git trailers in commit messages.

Core principle: A commit is not a label for a diff — it's an atomic unit of institutional knowledge. Use git's native trailer format so decisions are machine-queryable, not buried in prose.

When to Use

• Any commit where you made non-obvious decisions
• When you rejected alternative approaches
• When external constraints shaped your implementation
• When future modifiers need warnings about fragile assumptions
• When test coverage has known gaps

When NOT to use: Trivial changes (typo fixes, formatting) where no real decisions were made.

The Format

<imperative summary line>

<optional body explaining the change>

Constraint: <external constraint that shaped this decision>
Rejected: <alternative> | <reason it was rejected>
Confidence: <high | medium | low>
Scope-risk: <narrow | moderate | broad>
Reversibility: <clean | moderate | difficult>
Directive: <warning or instruction for future modifiers>
Tested: <what was verified>
Not-tested: <known coverage gaps>
Related: <commit hash or description of related commit>

All trailers are optional. Include only those that carry signal for this specific commit.

Trailer Vocabulary

You can repeat trailers (multiple Constraint:, multiple Rejected:, etc.).

You can extend the vocabulary with custom trailers when needed (e.g., Deadline:, Stakeholder:, Migration:).

Complete Example

Prevent silent session drops during long-running operations

The auth service returns inconsistent status codes on token
expiry, so the interceptor catches all 4xx responses and
triggers an inline refresh.

Constraint: Auth service does not support token introspection
Constraint: Must not add latency to non-expired-token paths
Rejected: Extend token TTL to 24h | security policy violation
Rejected: Background refresh on timer | race condition
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Error handling is intentionally broad (all 4xx)
  -- do not narrow without verifying upstream behavior
Tested: Single expired token refresh (unit)
Not-tested: Auth service cold-start > 500ms behavior

Why Git Trailers (Not Prose)

Agents naturally capture decision context as prose paragraphs. The problem: prose is not queryable.

Git trailers are a native git feature. Queryable with standard git tools:

# Query all constraints affecting a file
git log --all --grep="^Constraint:" -- path/to/file.ts

# Find all rejected approaches
git log --all --grep="^Rejected:" -- path/to/file.ts

# Find directives (warnings for future modifiers)
git log --all --grep="^Directive:" -- path/to/file.ts

# Check what's not tested
git log --all --grep="^Not-tested:" -- path/to/file.ts

This turns your git history into a queryable decision database at zero infrastructure cost.

Agent Workflow

When modifying code, before committing:

1. Harvest context — What constraints did you face? What alternatives did you reject?
2. Write the summary line — Imperative, focused on *why* not *what*
3. Add body if the *how* needs explanation
4. Append trailers — One per decision fact. Only include trailers that carry signal.
5. Self-check — Would a future agent modifying this code benefit from knowing this?

Common Mistakes