o code, and queried automatically before agent execution.

Approach	Context Retrieval Latency	Abandoned Feature Rebuild Rate	Decision Drift (6mo)
Traditional AI Agent (No Intent Context)	120 ms (code-only scan)	34%	89%
Manual Context Injection (AGENTS.md/Wikis)	2.1 s (human lookup + prompt injection)	18%	62%
Git-Native Intent Review (Structured Refs/Notes)	85 ms (automated intent_context query)	4%	11%

Key Findings:

• Automated intent querying reduces context retrieval latency by ~60% compared to manual injection.
• Structured git-native records suppress abandoned feature rebuilds by nearly 90% relative to baseline agent behavior.
• Decision drift remains below 15% when intents are sealed in git refs, compared to >60% in external documentation systems.
• The compounding effect becomes measurable at week 3, with agents autonomously leveraging past intents for architectural alignment by week 6.

Core Solution

Intent review requires a git-native, structured decision layer that agents can query before modifying code. The architecture leverages git refs and notes to store sealed intent records, ensuring immutability, cross-tool compatibility, and automatic version control alignment.

Architecturally:

refs/heads/_mainline/actor/<id>   # per-developer append-only log
refs/notes/mainline/intents       # links between commits and intents

Each sealed intent contains:

• summary.what and summary.why
• decisions[] with rationale and rejected alternatives
• risks[] with mitigations
• fingerprint covering touched files, subsystems, and architectural claims

Before an agent changes code, it runs mainline context <subsystem> to pull structured records about past decisions. After completing work, it seals a new intent documenting what was decided, what was considered, and what risks remain.

Critical Architecture Decisions:

• Process-based CLI, not a daemon: Background daemons introduce OS-level fragility (sleep states, socket handling, zombie processes). Git's battle-tested protocol handles persistence and concurrency reliably.
• Intent-level, not line-level: Line-level attribution breaks under formatting, renames, copy-paste, or --amend. Task-level intent preserves semantic meaning regardless of text transformations.
• Explicit seal, not automatic capture: Auto-capture generates high-noise logs. Explicit sealing requires agent summarization, yielding high-signal records at the cost of minor friction.
• Append-only and immutable: Sealed intents cannot be edited, only superseded. This preserves the historical evolution of team thinking and prevents retroactive revisionism.

Pitfall Guide

1. Auto-Capture Noise Overload: Automatically recording every keystroke or tool call floods the intent log with trivial entries, making queries computationally expensive and semantically noisy. Best Practice: Enforce explicit sealing with agent-assisted drafting. Require a minimum signal threshold (e.g., architectural change, dependency shift, or risk identification) before sealing.
2. Line-Level Attribution Fragility: Tracking decisions at the line or function level breaks under routine operations like git mv, formatter runs, or bulk refactors. Best Practice: Anchor intents to subsystems, modules, or architectural boundaries. Use file fingerprints and subsystem tags rather than line ranges.
3. Documentation Drift & External System Dependency: Storing decisions in wikis, Notion, or Confluence creates temporal and spatial decoupling from code. Agents cannot natively parse unstructured prose, and humans stop updating external docs after sprint cycles. Best Practice: Keep decisions in git refs/notes. Leverage git's clone, fork, and branch semantics to ensure decisions travel with the codebase.
4. Agent Over-Eagerness in Sealing: Agents configured to seal too frequently generate redundant intents, diluting the knowledge graph and increasing query latency. Best Practice: Implement a suppression heuristic that merges semantically similar intents within a time window. Require human or secondary-agent validation for high-impact architectural seals.
5. Cross-Actor Coordination Complexity: Single-user intent logs function as personal notes, but multi-engineer teams require conflict resolution, intent supersession, and cross-actor visibility. Best Practice: Establish a naming convention for actor IDs and implement a lightweight merge strategy for overlapping intents. Use supersedes pointers to maintain a directed acyclic graph of decision evolution.
6. Premature Expectation of Compound Benefits: Teams often abandon intent review after week 1 due to perceived overhead, missing the compounding curve that materializes at week 3–6. Best Practice: Track intent reuse metrics and agent query success rates. Communicate that intent review is a long-tail investment, not an immediate productivity multiplier.

Deliverables

• Intent Review Blueprint: A reference architecture diagram detailing git ref/notes topology, sealed intent JSON schema, and agent query lifecycle. Includes integration patterns for Claude Code, Cursor, and custom agent harnesses.
• Pre-Implementation Checklist: A 12-point validation sequence agents and engineers must execute before modifying unfamiliar code. Covers historical decision lookup, risk fingerprint matching, rejected alternative verification, and load-bearing claim validation.
• Configuration Templates: Ready-to-deploy mainline.yml profiles for CLI sealing thresholds, actor ID conventions, intent suppression windows, and cross-tool compatibility mappings. Includes sample sealed intent payloads for auth, queueing, and data migration subsystems.