# Intent Tracking

*The why of a change, captured and validated against the what.*

A commit message is an honor system. The author writes a sentence describing what they did; nobody checks whether the sentence is true. In small teams on careful days, this works. In large teams, in fast-moving codebases, and especially in codebases edited by AI agents, it does not. Commit messages drift from reality. A change described as "fixed typo" removes a feature. A change described as "refactored for clarity" changes behavior. The message and the code no longer agree.

Aura fixes this by treating intent as first-class data. Before a commit, you log your intent — a stated description of what you mean to change. At commit time, Aura computes the AST delta and compares it to the stated intent. When they disagree, the commit is flagged.

> A commit without intent is a commit without a hypothesis. You cannot test what is not stated.

## Intent as a promise

Logging intent is a promise you make to the tool. You say: "I am about to refactor `retry_logic` to use exponential backoff." The tool holds you to it. If the actual changes are not a refactor of `retry_logic`, if they add new behavior, if they delete unrelated functions, Aura notices.

```bash
aura_log_intent "Refactored retry_logic to use exponential backoff for rate limit compliance"
```

The intent is stored in the session. It is linked to the changes that follow. At commit time, the pre-commit hook runs semantic diff against the intent and produces a verdict: consistent, inconsistent, or ambiguous.

## Intent poisoning

The pathological case is what Aura calls **intent poisoning**: the stated intent and the actual change disagree in a way that suggests the author (or agent) is describing one change while making another. This happens intentionally (rare) and unintentionally (common). An AI agent tasked with "fix a typo" sometimes rewrites a function. A human tired at 2 a.m. forgets to revert a stray edit. A collaborator pasting from a different branch brings changes they did not announce.

Intent poisoning is not a security concept — it is a consistency concept. The question Aura asks is: does the description match the delta?

A few real patterns it catches:

- Intent says "fix typo in docs." Delta shows a function body modified. Flagged.
- Intent says "add new endpoint." Delta shows an existing endpoint deleted. Flagged.
- Intent says "refactor for readability." Delta shows signature changes on public functions. Flagged as an API change that was not declared.
- Intent says "update dependency." Delta shows application code changes. Flagged.

Each of these is something a careful reviewer would notice. Aura notices them consistently, at commit time, before the change lands.

## How the comparison works

The pre-commit hook has three inputs:

1. The **intent** — natural-language, from the session log.
2. The **semantic diff** — structured, from the [AST comparison](/semantic-diff) of the staged changes.
3. A **classifier** — a model that asks whether the diff is a plausible realization of the intent.

The classifier's answer is not binary. It produces a score and a reason:

```json
{
  "intent": "Refactored retry_logic to use exponential backoff",
  "diff_summary": {
    "functions_modified": ["retry_logic", "backoff_delay"],
    "functions_added": ["exponential_interval"],
    "signatures_changed": []
  },
  "verdict": "consistent",
  "confidence": 0.94
}
```

Or:

```json
{
  "intent": "Fixed typo in README",
  "diff_summary": {
    "functions_modified": ["authenticate", "refresh_token"],
    "docs_changed": ["README.md"]
  },
  "verdict": "inconsistent",
  "reason": "Intent mentions only docs, but 2 functions were modified",
  "confidence": 0.99
}
```

The verdict is exposed to the author. In strict mode, an inconsistent verdict blocks the commit. In non-strict mode, it is surfaced as a warning and recorded alongside the commit for later review. See [pre-commit hook explained](/pre-commit-hook-explained).

## Intent as a review aid

Intent is also the best possible summary for a reviewer. A reviewer looking at an Aura commit sees:

- The intent sentence.
- The semantic diff (node-level operations).
- The verdict.

They can read the intent, scan the diff to confirm, and approve. If intent and diff agree, reviewing is a matter of confirming the hypothesis. If they disagree, the reviewer has a precise place to look.

This is qualitatively different from reviewing a Git diff. Git diffs require the reviewer to infer intent from the changes; Aura diffs provide the intent and let the reviewer verify it.

## Granularity

Intent is logged at whatever granularity makes sense. For a small change, a single sentence covers everything. For a larger change, multiple intents are logged in sequence:

```bash
aura_log_intent "Extracted token validation into its own function"
# ... edit ...
aura_log_intent "Added rate limiting middleware to validation endpoint"
# ... edit ...
aura_log_intent "Updated tests for new rate limiting behavior"
```

At commit time, Aura matches each intent to a corresponding slice of the diff. Commits with multiple intents are merged into a single commit record but the intent breakdown is preserved — a reviewer can see the logical sequence even though the commit is atomic.

## Sessions make intent durable

Intent is tied to a [session](/session-model). Within a session, intents accumulate. If you do not commit between intents, the session's intent log is the record of what you were trying to do. This is valuable in two cases:

- **Handover.** An agent can hand over work mid-session, and the successor reads the intent log to understand what was in progress.
- **Session rewind.** You can rewind a session and replay or discard individual intents, not the whole commit.

Commits are checkpoints; intents are the narrative between checkpoints. Both are preserved.

## Intent for AI agents

Intent was designed with AI agents in mind. An agent without intent is a black box — it produces diffs with no explanation, and humans are left to reverse-engineer. An agent that logs intent is legible. The agent says "I am going to do X," then does X, and the tool confirms X was done.

The protocol for agents:

1. Before starting a task, the agent logs its intent.
2. The agent makes the change.
3. The pre-commit hook validates.
4. If the validation fails, the agent either fixes the change or updates the intent — explicitly acknowledging the discrepancy.

A fleet of agents working under this protocol leaves a trail of intent + diff + verdict for every change. The trail is auditable. The trail is the single most important artifact for trusting AI-generated code in production.

## What intent cannot do

Intent tracking is not a guarantee of correctness. An intent like "add null check" paired with a diff that adds a null check is judged consistent — even if the null check is in the wrong place, or missing cases, or subtly buggy. Intent validation answers "does the change match the stated plan?" It does not answer "is the plan a good one?" or "is the change correct?"

For correctness, Aura offers other tools: [pr-review](/pre-commit-hook-explained), [prove](/semantic-diff) for goal-level verification, tests. Intent is a consistency layer. It does not replace reasoning about the code — it makes the reasoning recorded and checkable.

## Intent in the commit record

The final commit includes the intent as structured metadata, not just a message. A reviewer looking at the commit sees:

- Git message (human-authored, short).
- Aura intent (declarative, what the author said they were doing).
- Semantic diff summary.
- Verdict and confidence.

Six months later, a developer debugging a regression can ask: "when was `retry_logic` last touched, and why?" Aura answers both questions from the record. "Last modified in commit 7c9f21, with intent: refactored to use exponential backoff for rate limit compliance. Verdict: consistent."

This is the historical record real teams actually need.

## Philosophy: declaring over describing

A commit message describes what you did. An intent declares what you meant to do. The grammatical difference is small; the epistemic difference is large.

A description is a report after the fact, verifiable only against other descriptions. A declaration is a hypothesis, verifiable against the actual delta. Aura is built on declarations because declarations can be checked.

This is the same reason type systems work better than comments: one is mechanically verifiable, the other is not. Intent tracking is, in effect, a type system for the *why* of a change — coarse, natural-language, but checked by the tool every time you commit.

## Related

Intent is validated by the [pre-commit hook](/pre-commit-hook-explained) against the [semantic diff](/semantic-diff). It is stored in the [session](/session-model) and persists across handover and rewind.