Paper deep dive

Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents

Ivan Stetsenko

Year: 2026Venue: arXiv preprintArea: cs.SEType: PreprintEmbeddings: 22

Intelligence

Status: succeeded | Model: google/gemini-3.1-flash-lite-preview | Prompt: intel-v1 | Confidence: 95%

Last extracted: 3/22/2026, 5:24:11 AM

Summary

Lore is a lightweight protocol that repurposes Git commit messages as structured knowledge records using native Git trailers. It addresses the 'Decision Shadow'—the loss of reasoning, constraints, and rejected alternatives during software development—by embedding this context directly into the immutable Git history, making it queryable for AI coding agents via a CLI tool without requiring external infrastructure.

Entities (5)

Git Trailers · technology · 100%Lore · protocol · 100%AI Coding Agents · agent · 95%Architecture Decision Records · methodology · 95%Decision Shadow · concept · 95%

Relation Signals (4)

Lore → uses → Git Trailers

confidence 100% · Lore uses git trailers—a native git feature for structured key-value data in commit messages.

Lore → addresses → Decision Shadow

confidence 95% · Lore identifies the same problem [Decision Shadow] but proposes a radically lighter-weight treatment

Lore → comparedto → Architecture Decision Records

confidence 90% · Lore addresses the complementary granularity—implementation decisions—and eliminates the synchronization problem [of ADRs]

AI Coding Agents → consumes → Lore

confidence 90% · Lore is a protocol... discoverable by any agent capable of running shell commands.

Cypher Suggestions (0)

No Cypher suggestions yet.

Abstract

Abstract:As AI coding agents become both primary producers and consumers of source code, the software industry faces an accelerating loss of institutional knowledge. Each commit captures a code diff but discards the reasoning behind it - the constraints, rejected alternatives, and forward-looking context that shaped the decision. I term this discarded reasoning the Decision Shadow. This paper proposes Lore, a lightweight protocol that restructures commit messages - using native git trailers - into self-contained decision records carrying constraints, rejected alternatives, agent directives, and verification metadata. Lore requires no infrastructure beyond git, is queryable via a standalone CLI tool, and is discoverable by any agent capable of running shell commands. The paper formalizes the protocol, compares it against five competing approaches, stress-tests it against its strongest objections, and outlines an empirical validation path.

PDF

Open source PDF →Open local PDF →

Trouble viewing inline? Open PDF directly →

Full Text

21,441 characters extracted from source content.

Expand or collapse full text

Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents Ivan Stetsenko Independent Researcher dev.ivan.stetsenko@gmail.com March 2026 Abstract As AI coding agents become both primary producers and consumers of source code, the software industry faces an accelerating loss of institutional knowledge. Each commit captures a code diff but discards the reasoning behind it—the constraints, rejected alternatives, and forward-looking context that shaped the decision. I term this discarded reasoning the Decision Shadow. Prior work has identified this tacit knowledge gap as a critical bottleneck for AI-assisted development [1,2] and has proposed heavyweight infrastructure to address it, including knowledge graphs [1], version-controlled agent memory systems [3], and separate Architecture Decision Records [4]. This paper argues that the solution already exists in every software project: the git commit message. I propose Lore, a lightweight protocol that restructures commit messages—using native git trailers—into self-contained decision records carrying constraints, rejected alternatives, agent directives, and verification metadata. Lore requires no infrastructure beyond git, is queryable via a standalone CLI tool, and is discoverable by any agent capable of running shell commands. This paper formalizes the protocol, compares it against five competing approaches, stress-tests it against its strongest objections, and outlines an empirical validation path. To the best of my knowledge, Lore is the first proposal to repurpose the commit message itself as a structured, machine-parseable knowledge channel optimized for inter-agent communication across time. 1 Introduction 1.1 The Decision Shadow Every commit in a software project is the visible output of an invisible process. A developer (or AI agent) encounters a problem, considers several possible approaches, evaluates the tradeoffs, selects one, and implements it. The commit captures exactly one artifact from this process: the final diff. Everything else—the problem definition, the alternatives considered, the reasons for rejection, the constraints that shaped the decision, the confidence level, the known weaknesses—evaporates. I call this lost context the Decision Shadow: the unrecorded reasoning behind why the code looks the way it does at any given point. Over time, Decision Shadows accumulate. Each one is individually small. Collectively, they produce what the industry calls “legacy code”—code that functions but whose structural rationale is lost. Peng and Wang [1] describe this phenomenon as “tacit knowledge” that “often lives in developer experience or informal artifacts rather than in code” and observe that 1 arXiv:2603.15566v1 [cs.SE] 16 Mar 2026 “current [AI] assistants cannot reliably retrieve or reconstruct this knowledge on demand.” 1.2 The Commit Message as It Exists Today The Conventional Commits specification [5], the closest approximation to an industry stan- dard, encodes a message astype(scope): short description. This tells you what happened (fix(auth): handle expired token refresh) but is nearly useless for understanding why the code evolved the way it did. The problem is structural, not motivational. The format was designed for a world where humans were the only consumers of commit history, the diff was the primary artifact, and deep context lived in people’s heads—transmitted orally through standups, pull request reviews, and hallway conversations. All three assumptions are collapsing. 1.3 Why This Matters Now Two shifts make the Decision Shadow problem urgent. Shift 1: AI agents are now primary code consumers. Tools such as Claude Code [6], GitHub Copilot [7], and Cursor [8] attempt to reconstruct intent and constraints from existing code when tasked with modifications. The code tells them what exists; tests tell them what should be true; the commit history should tell them why—but in practice, messages like refactor: clean up utils transmit near-zero signal. Shift 2: AI agents are now primary code producers. When an agent generates a commit, the message it writes is typically a summary of the diff—a lossy compression of information already present. Research from GitClear analyzing 153 million changed lines of code found that AI coding tools are introducing code faster than ever while raising concerns about long-term maintainability [9]. No decision context is added to commits. The knowledge destruction problem is accelerating. The compound result: codebases are growing faster than ever while the ratio of recorded institutional knowledge to code volume is decreasing. 2 Related Work 2.1 Architecture Decision Records Architecture Decision Records (ADRs), popularized by Nygard [4] in 2011, capture high- level architectural decisions as standalone documents. The format typically includes a title, context, decision, and consequences. ADRs have gained adoption in government [10] and enterprise settings [11], and tools such as Log4brains [12] provide management and publication infrastructure. ADRs operate at the architectural granularity—explaining choices such as “why we chose PostgreSQL over MongoDB”—but do not capture implementation-level decisions: why a particular function handles errors the way it does, what alternatives were considered for a specific module’s retry logic, or what constraints shaped a data validation approach. These implementation decisions are far more numerous than architectural decisions and are the ones most commonly lost. Furthermore, ADRs suffer from a synchronization problem: as separate files, they must be manually maintained alongside an evolving codebase and routinely go stale [10]. Lore addresses the complementary granularity—implementation decisions—and eliminates the synchronization problem by embedding knowledge directly 2 in the commit, which is immutable and atomically bound to the code change. 2.2 Code Digital Twin Peng and Wang [1] propose the Code Digital Twin, a “living knowledge infrastructure that couples a physical layer of software artifacts with a conceptual layer that encodes system intent and evolution.” Their diagnosis of the problem aligns strongly with the one presented here: tacit knowledge including “architectural rationales, design trade-offs, and historical context” is critical for AI-assisted development, and “capability gains alone do not eliminate the need for structured, version-aware context that preserves why the system is the way it is.” However, their proposed solution is architecturally heavyweight: a multi-layered infras- tructure involving knowledge graphs, bidirectional traceable links between code artifacts and conceptual models, and continuous automated extraction pipelines. While this may be appropriate for large enterprise systems such as the Linux kernel (their motivating example), it represents significant infrastructure investment that most projects cannot undertake. Lore identifies the same problem but proposes a radically lighter-weight treatment: enriching an artifact every project already has (commit messages) using a mechanism git already supports (trailers), queryable through a tool every agent already knows how to use (a CLI). 2.3 Git Context Controller The Git Context Controller (GCC) [3] proposes a structured context management framework for AI agents, using git-inspired operations (COMMIT, BRANCH, MERGE, CONTEXT) over a.GCC/directory to organize agent memory as a versioned file system. The authors report state-of-the-art results on the SWE-Bench benchmark when agents are equipped with GCC. GCC and Lore address different aspects of the agent context problem. GCC is an intra- session memory management system: it helps an agent organize its own working memory during a task, with checkpointing and branching to support exploration. Lore is an inter- session knowledge transfer mechanism: it encodes decision context into the permanent project history so that future agents (or humans) benefit from it. GCC manages the agent’s scratchpad; Lore manages the project’s institutional memory. The two are complementary— an agent could use GCC during a task and produce a Lore-enriched commit at the end. 2.4 AI Code Attribution and Provenance The git-ai project [13] tracks which lines of code were written by AI agents, linking every AI-authored line to the agent, model, and original prompt transcripts. Their/askskill allows agents to query the original intent and requirements behind code they are modifying, providing what the authors describe as access to “the why” rather than just “what the code does.” Git-ai preserves the raw transcript—the full conversation between human and agent. Lore preserves the distilled knowledge—the constraints, rejected alternatives, and directives extracted from that conversation. These are related but distinct: the transcript is the raw material, Lore is the refined product. A transcript for a single feature might be thousands of tokens of back-and-forth; the corresponding Lore commit is a dozen structured trailers. For consumption by future agents operating under context window constraints, the compression from transcript to structured knowledge is critical. 3 2.5 AI-Generated Commit Messages A large ecosystem of tools—including aicommits [14], Windsurf’s built-in feature [15], and Cursor’s commit generation [8]—use AI to automatically generate commit messages from diffs. These tools improve consistency and save developer time, but they fundamentally oper- ate as better labelers of diffs: they describe what changed, not why. As one practitioner noted, while AI handles “consistency and technical summaries” well, it cannot capture “the ‘why’ behind our changes—the business context, user feedback, or strategic decisions” [16]. Lore proposes a categorically different kind of information in commits—not a better description of the diff, but knowledge that was never in the diff at all. 3 The Lore Protocol 3.1 Core Thesis A commit should not be a label on a diff. It should be the atomic unit of institutional knowl- edge in a software project—the smallest self-contained record of a decision, permanently and immutably bound to the code change that enacted it. I call this unit a Lore atom. Its defining properties: Atomic binding. The knowledge is permanently fused to the exact code change it describes. Unlike documentation, wikis, ADRs, or chat threads, it cannot drift out of sync—the commit and its message are a single immutable object. Temporal immutability. Once committed, the Lore atom exists permanently in the project history. It forms an append-only log of decisions—a stronger guarantee than any documenta- tion system provides. Universal availability. Every git-based project already has this channel. There is zero infrastructure cost. The distribution mechanism (clone, fetch, pull) is already solved. Natural granularity. Commits are already scoped to logical units of work. The Lore atom inherits this scoping for free. 3.2 Format: Git Trailers Lore uses git trailers—a native git feature for structured key-value data in commit messages. This choice is deliberate: no custom parsing is required, the format is queryable through standard git commands (git log -trailer=), and it is supported by every git tool in existence. A Lore-enriched commit takes the following form (Figure 1): The intent line (first line) describes why the change was made, not what changed. The body provides narrative context. The trailers carry machine-parseable decision context. The trailer vocabulary is shown in Table 1. Every trailer is optional. The format is additive and extensible: unknown keys are ignored, and teams can introduce domain-specific trailers without breaking compatibility. 3.3 The CLI: Querying and Authoring Lore While raw Lore trailers are readable in anygit logoutput, a CLI tool provides efficient, scoped querying (Figure 2): 4 Prevent silent session drops during long-running operations The auth service returns inconsistent status codes on token expiry, so the interceptor catches all 4x 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 4x) -- do not narrow without verifying upstream behavior Tested: Single expired token refresh (unit) Not-tested: Auth service cold-start > 500ms behavior Figure 1: Example of a Lore-enriched commit message. Table 1: Lore trailer vocabulary. TrailerSemantics Constraint:Rules that shaped this decision and may still be active Rejected:Alternatives evaluated and dismissed, with reasons Confidence:Author’s assessment: low, medium, high Scope-risk:Blast radius: narrow, moderate, wide Reversibility: clean, migration-needed, irreversible Directive:Forward-looking instructions for future modifiers Tested:What was verified and how Not-tested:What was not verified and why Related:Reference to related commits by hash 3.4 Agent Consumption Model When an AI coding agent enters a Lore-enabled project, the consumption workflow unfolds through discoverable CLI interactions: Discovery. The agent encounters a.loreconfig file or Lore-formatted commits ingit log, and runs lore -help to understand the available commands. Constraint harvest. Before modifying any file, the agent runslore context <path> to load the full decision history into its working context. Anti-pattern filtering.Rejected:trailers prevent the agent from re-exploring dead ends. Directive absorption.Directive:trailers function as messages from previous authors to future modifiers—permanent, searchable institutional knowledge. Temporal reasoning. Thelore stalecommand surfaces constraints that may be out- dated, enabling a self-healing knowledge base. Knowledge serialization. The agent formats its own commit as a Lore atom, serializing decision context it already holds rather than discarding it. 5 $ lore --help Lore -- Query and author institutional knowledge from git history Query commands: lore context <path> Full lore summary for a code region lore constraints <path> Active constraints shaping this code lore rejected <path> Previously rejected alternatives lore directives <path> Forward-looking warnings lore coverage <path> Test coverage map lore stale [--older-than] Flag outdated assumptions Authoring commands: lore commit Interactive commit builder lore commit --from-json Commit from structured input lore validate Check recent commits for lore format Figure 2: Lore CLI interface. The critical property is that zero special agent support is required—only the ability to run shell commands and read text output. 4 Analysis: Why Not Something Else? vs. ADRs. Complementary, not competing. ADRs capture architectural decisions; Lore captures implementation decisions. ADRs are separate files subject to synchronization decay; Lore atoms are immutably bound to code changes. vs. Code Comments. Comments are mutable, routinely inaccurate, and cannot capture trajectory. Lore preserves the full ordered history of decisions. vs. AI-Generated Diff Summaries. Diff summaries [14,15] re-encode information already in the diff. Lore adds information that was never in the diff : rejected alternatives, external constraints, confidence assessments, and forward-looking warnings. vs. RAG Over External Sources. Chat-based RAG suffers from low signal-to-noise, no atomic binding, and ephemeral access. Lore inverts all three. vs. Code Digital Twin. The Code Digital Twin [1] prescribes heavyweight infrastructure. Lore offers near-zero infrastructure cost for the vast majority of projects that cannot justify a full knowledge layer. 5 Critical Examination Overhead objection. Lore is situated in the AI agent era. Agents already hold decision context and can serialize it at commit time; the overhead is review, not authoring. Residual risk: rubber-stamped low-quality atoms require lore validate checks. Context window objection. No context window expansion recovers information never written down. Rejected alternatives and external constraints exist only in the author’s mind at commit time. Concession: Lore’s value is primarily inter-session and inter-agent. Trust and gaming. Structured format makes quality measurable and auditable. Concession: 6 Lore does not solve the trust problem; it makes trust auditable. Granularity mismatch. TheRelated:trailer supports commit chains. Concession: ADRs [4] remain better for cross-cutting architectural decisions. 6 Architecture Lore has exactly two layers. Layer A is the commit format—git trailers in standard messages, requiring zero tooling. Layer B is the CLI tool—providing efficient querying and authoring. The CLI is optional; the format is sufficient. No servers, no index files, no databases. Additional tools can be built on top without becoming part of the core protocol. 7 Adoption Path and Validation Lore degrades gracefully: best experience with the CLI, fallback via nativegit log -trailer=, and no worse than today in conventional repos. The adoption curve is agent- first: AI agents produce Lore commits with zero friction. Conventional Commits [5] took years because humans had to type them; Lore shifts the burden to agent configuration. Proposed empirical validation: Two teams, same project, six months. One uses Lore; one uses conventional commits. Measured outcomes: agent task success rate, time-to-correct- solution, rate of re-proposing rejected approaches, and review cycles before merge. 8 Conclusion This paper has argued that the git commit message is critically underutilized as a knowledge channel. I have proposed Lore, a protocol that repurposes commit messages into structured decision records using native git trailers, queryable through a CLI that any AI agent can discover and use. The core insight is that every commit already produces institutional knowledge that is currently discarded. Lore asks agents and developers to serialize this knowledge rather than throw it away. The overhead is minimal; the infrastructure requirement is zero; and the value compounds over time through a knowledge flywheel that conventional commits cannot produce. To the best of my knowledge, no prior work has proposed the commit message itself as the vehicle for structured, machine-parseable decision context optimized for AI agent consumption. Lore operates at the simplest possible layer. This minimalism is a feature, not a limitation. Every codebase has lore. Most of it is lost. The protocol proposed here is a first step toward changing that. Disclosure of AI-Assisted Tools The author used AI-assisted tools during the research and writing process for this paper. Specifically, Claude (Anthropic, claude-opus-4-6) was used as an interactive research collab- orator for brainstorming the core thesis, iterating on protocol design decisions, conducting structured literature review, and drafting and refining text. Google NotebookLM was used for organizing and synthesizing research materials. All intellectual contributions—including the identification of the Decision Shadow problem, the Lore protocol design, the choice of 7 git trailers as the implementation mechanism, the CLI-first architecture, and the comparative analysis against competing approaches—originated from the author’s own reasoning, with AI tools serving as instruments for exploration, articulation, and refinement. The author reviewed, edited, and takes full responsibility for all content in this paper. References [1]X. Peng and C. Wang, “Code Digital Twin: Empowering LLMs with Tacit Knowledge for Complex Software Development,” arXiv preprint arXiv:2503.07967, 2025. [2]V. Terragni, A. Vella, P. Roop, and K. Blincoe, “The Future of AI-Driven Software Engineering,” ACM Trans. Softw. Eng. Methodol., 2025. [3]“Git Context Controller: Manage the Context of LLM-based Agents like Git,” arXiv preprint arXiv:2508.00031, 2025. [4] M.Nygard,“DocumentingArchitectureDecisions,”Novem- ber2011.https://cognitect.com/blog/2011/11/15/ documenting-architecture-decisions [5] “ConventionalCommitsSpecificationv1.0.0.”https://w. conventionalcommits.org/ [6]Anthropic, “Claude Code,” 2025.https://docs.anthropic.com/en/docs/ agents-and-tools/claude-code/overview [7]GitHub, “GitHub Copilot,” 2025.https://github.com/features/copilot [8] Anysphere, “Cursor: The AI Code Editor,” 2025. https://cursor.com [9]B. Harding, “Coding on Copilot: 2023 Data Suggests Downward Pressure on Code Quality,” GitClear, 2024. [10]18F (U.S. General Services Administration), “Architecture Decision Records: Helpful now, invaluable later,” July 2021. [11] D. Haylock, “The Importance of Architecture Decision Records (ADRs),” Medium, March 2025. [12] T. Vaill, “Log4brains: ADR management and publication tool.”https://github. com/thomvaill/log4brains [13] A. Cunniffe, “Git AI: A Git extension for tracking AI-generated code,” 2025.https: //usegitai.com [14] H. Nasser, “aicommits: A CLI that writes your git commit messages with AI.”https: //github.com/Nutlope/aicommits [15]Windsurf, “AI Commit Messages,” 2025.https://docs.windsurf.com/ windsurf/ai-commit-message [16]C. Lawson, “Git Commit: When AI Met Human Insight,” Versent Tech Blog, September 2024. 8

Instant research discovery