Lore Commit Protocol in oh-my-codex: How to Implement Structured Decision Records

The Lore Commit Protocol transforms standard git commits into machine-readable decision records by requiring an intent-first message line and structured git trailers such as Constraint:, Confidence:, and Directive: to capture decision rationale.

The Lore Commit Protocol is the standardized commit message format used throughout the oh-my-codex repository to ensure every code change carries its full decision context. Instead of describing what changed in the diff, Lore commits explain why the change was necessary, what alternatives were rejected, and what risks remain, creating a searchable knowledge base directly within your git history.

What Is the Lore Commit Protocol?

The Lore Commit Protocol is defined in templates/AGENTS.md and serves as the mandatory standard for every git commit inside the oh-my-codex repository. It treats each commit as a tiny, self-contained decision record rather than a simple change summary, ensuring that future agents and developers can understand the rationale without reverse-engineering the diff.

According to the source code, the protocol consists of three distinct sections: an intent line that states why the change exists, an optional narrative body providing context, and structured git trailers that encode metadata like constraints, rejected alternatives, and confidence levels.

Core Components of a Lore Commit

The Intent Line

The first line of every Lore commit must describe why the change was made, not what the diff shows. This intent line answers the decision question rather than describing the mechanics.

For example, use Prevent silent session drops during long-running operations instead of Update auth interceptor to catch 4xx errors. This convention forces the author to document the problem being solved rather than the implementation detail.

The Narrative Body

After the intent line, you may include an optional body separated by a blank line. This section adds narrative context such as technical constraints, approach justifications, or architectural notes that cannot fit in a single line.

The body in templates/AGENTS.md is described as the place to explain "constraints, approach, etc."—for instance, detailing why a particular auth service behavior necessitated a specific error-handling strategy.

Structured Git Trailers

Following a blank line after the body (or immediately after the intent line if no body exists), you append structured git trailers using the vocabulary defined in templates/AGENTS.md. These are key-value pairs in the format Key: value.

The canonical trailer vocabulary includes:

• Constraint: – External limitations affecting the decision (e.g., "Auth service does not support token introspection")
• Rejected: – Alternatives explicitly considered and discarded (e.g., "Extend token TTL to 24h | security policy violation")
• Confidence: – Certainty level (e.g., "high", "medium", "low")
• Scope-risk: – Impact surface area (e.g., "narrow", "wide")
• Directive: – Warnings to future modifiers (e.g., "Do not narrow error handling without upstream verification")
• Tested: – Validation performed
• Not-tested: – Known untested scenarios
• Related: – Cross-references to other commits or issues

Rules for trailers:

1. Only include trailers that add value—omit irrelevant categories
2. The Rejected: trailer specifically blocks future re-exploration of discarded alternatives
3. The Directive: trailer warns future developers about modification constraints

How to Write a Structured Decision Record

To implement a Lore commit, follow the exact layout: intent line, optional body, blank line, then trailers. Here is a minimal example demonstrating the format:

Prevent silent session drops during long-running operations

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

Constraint: Auth service does not support token introspection
Rejected: Extend token TTL to 24h | security policy violation
Confidence: high
Scope-risk: narrow
Directive: Do not narrow error handling without upstream verification
Tested: Unit test for expired-token refresh
Not-tested: Auth service cold-start >500ms behavior

Full Shell Workflow

Use a here-document to compose complex Lore commits directly from the command line:

# Stage your changes

git add src/auth/interceptor.ts

# Commit with structured trailers

git commit -F - <<'EOF'
Prevent silent session drops during long-running operations

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

Constraint: Auth service does not support token introspection
Rejected: Extend token TTL to 24h | security policy violation
Confidence: high
Scope-risk: narrow
Directive: Do not narrow error handling without upstream verification
Tested: Unit test for expired-token refresh
Not-tested: Auth service cold-start >500ms behavior
EOF

Automating Validation and Parsing

Because Lore commits use standard git trailers, you can automate validation in CI pipelines and extract metadata for release notes.

Validating Required Trailers

Save this script as tools/validate-lore.sh to enforce that commits contain mandatory trailers like Constraint: and Tested::

#!/usr/bin/env bash

# validate-lore.sh – exits 0 if required trailers are present

msg=$(git log -1 --pretty=%B)

required=("Constraint:" "Tested:" "Confidence:")

for key in "${required[@]}"; do
  if ! grep -q "^${key}" <<<"$msg"; then
    echo "Missing required Lore trailer: $key"
    exit 1
  fi
done
echo "All required Lore trailers present."

Parsing Trailers with Python

For automation tooling, use this Python script to parse trailers into a dictionary:

import subprocess
from pathlib import Path

def get_last_commit_message():
    return subprocess.check_output(
        ["git", "log", "-1", "--pretty=%B"], text=True
    ).strip()

def parse_trailers(message: str) -> dict:
    trailers = {}
    for line in message.splitlines():
        if ":" in line:
            key, value = line.split(":", 1)
            key = key.strip()
            value = value.strip()
            if key and value:
                trailers.setdefault(key, []).append(value)
    return trailers

msg = get_last_commit_message()
trailers = parse_trailers(msg)
print("Lore trailers found:", trailers)

Agent Integration and Enforcement

The oh-my-codex repository integrates the Lore protocol directly into agent workflows. The executor prompt located in prompts/executor.md contains a lore_commits block (lines 54-66) that reminds agents to write Lore-style messages before completing any task.

You can enforce the protocol in Continuous Integration by running the validation script against pull request commits. Additionally, release tooling can use commands like git log --format=%B | grep '^Constraint:' to auto-populate a "Decision Log" section in your changelog, as demonstrated in the repository's CHANGELOG.md.

Summary

• The Lore Commit Protocol requires every commit to explain why via an intent-first message line, turning git history into a decision archive.
• Structured trailers (Constraint:, Rejected:, Confidence:, etc.) provide machine-readable metadata defined in templates/AGENTS.md.
• The Rejected: trailer prevents future developers from re-exploring discarded alternatives, while Directive: warns against specific modifications.
• Validation scripts can parse standard git trailers to enforce compliance and generate documentation automatically.
• The executor agent in prompts/executor.md is explicitly instructed to use Lore commits for all changes in the oh-my-codex repository.

Frequently Asked Questions

What is the difference between a Lore commit and a conventional commit?

A conventional commit focuses on describing what changed in the diff (e.g., "fix auth interceptor"), while a Lore commit explains the decision rationale using an intent line describing why the change exists, supported by structured trailers that capture constraints, rejected alternatives, and confidence levels. This transforms the commit from a change log entry into a self-contained decision record.

Where is the Lore Commit Protocol defined in oh-my-codex?

The master specification lives in templates/AGENTS.md, which defines the intent line format, the trailer vocabulary (including Constraint:, Rejected:, and Directive:), and the formatting rules. The protocol is referenced by the executor agent in prompts/executor.md (lines 54-66), which reminds agents to apply Lore formatting when committing code.

How do I enforce Lore commits in CI/CD pipelines?

Add a validation step that runs a script like tools/validate-lore.sh to check for required trailers such as Constraint: and Tested:. Because Lore uses standard git trailers, you can use git log --grep to search for specific constraints or parse commit messages with Python to extract metadata and fail builds when mandatory fields are missing.

Can I customize the trailer vocabulary for my team?

The canonical vocabulary in templates/AGENTS.md includes specific keys like Scope-risk: and Not-tested: designed to support decision archaeology in oh-my-codex. While the protocol allows optional trailers (omit what adds no value), sticking to the defined vocabulary ensures compatibility with the repository's automated parsing tools and agent prompts. For external projects, you may extend the pattern, but consistency with the core keys maximizes utility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}