Grounding Has Four Values

Most of the code in our repos is written by agents. For the first stretch we reviewed that code the way you review a contractor's work: read the diff, run the tests, merge or send it back. That holds up until the failure mode changes shape. A bad diff is visible. A diff that is correct in form, passes its tests, and rests on something the agent invented is not visible at all. The function is clean. The claim underneath it (that a config loader honors a particular environment variable, that an upstream endpoint returns a particular field) was never checked against anything. It was produced, fluently, in the same voice as the checked claims.

So we moved the review surface. Instead of only inspecting the output, we made the path that produced the output into an artifact.

The log

The rule in our process doc is short:

Agents log reasoning to grimoires/loa/a2a/trajectory/{agent}-{date}.jsonl

One line per action, append-only, in JSON Lines so that a partial file is still a readable file and a crashed run still yields everything up to the crash. The shape:

{"timestamp": "...", "agent": "...", "action": "...", "reasoning": "...", "grounding": {...}}

Four of those fields are bookkeeping. The interesting one is grounding, and the reason it is interesting is that it is a closed set, not free text.

Four values

Grounding takes one of four types:

• citation: a direct quote from docs
• code_reference: a reference to existing code
• assumption: an ungrounded claim, which must be flagged
• user_input: based on a user request

We want to be precise about what this does, because the temptation is to describe it as a hallucination fix. It is not. A model can label an assumption as a citation, and nothing in the log stops it. What the closed set does is make the ungrounded case nameable and therefore countable. Before, an assumption and a citation arrived in identical prose, which meant the reviewer had to re-derive the provenance of every sentence by hand. Now the agent has to pick a bucket, and picking assumption is the cheap, available, non-punished option. The whole design rests on that: flagging has to be easier than fabricating a source.

The paired rule in the doc is that every claim cites a source or is flagged as [ASSUMPTION]. That is a strong requirement and we state it as the standard rather than as an achieved property. What we can say is that once the standard exists, the gap between the standard and the log is itself reviewable. An audit becomes a filter, not a reading.

This is the same instinct behind agent evaluation in Google's ADK, which scores the trajectory (the sequence of steps and tool calls) separately from the final response. Our version is coarser and lives in the repo rather than in a harness, but the premise is shared: for a multi-step agent, the answer and the route to the answer are two different things to be correct about, and only one of them shows up in the diff.

Not tracing

The obvious comparison is distributed tracing, and the comparison is instructive mostly where it breaks. A span in OpenTelemetry records that an operation happened, how long it took, and how it nested. It is about mechanism. A trajectory line records why the agent believed the operation was the right one, and what that belief was standing on. It is about warrant.

That difference changes who the log is for. Traces are read when something breaks. Trajectory logs are read when nothing appears to have broken, which is the harder case, and the case where agent-written code actually costs us. Hallucination) that produces failing code is self-limiting. Hallucination that produces passing code is a debt that pays out later, usually into a different repo.

Three scenarios

The second half of the decision is a floor on evidence: a minimum of three test scenarios before a task is marked complete.

Three is not a magic number and we do not defend it as one. It is a floor chosen to defeat a specific pattern, which is the single happy-path test written after the fact to justify a completion claim. One test can be selected to pass. Three force at least a gesture at the boundary of the change. The number is the smallest one that makes the shortcut visibly insufficient, and we would rather have a low floor that holds than a high one that gets negotiated away every time an agent is near the end of a task.

This is the part of the protocol that binds the other part. A trajectory log that ends in "task complete" with no scenarios attached is a claim like any other claim, and it needs its own grounding.

What it costs

Honest accounting, all of it unmeasured and offered as an estimate rather than a result:

1. Every action carries writing overhead. The log lines are small, but there is one per action and the files accumulate per agent per day.
2. Reasoning fields are written by the same process whose reasoning is under review. They are self-reports. Their evidentiary value is real but bounded, and we treat them that way.
3. Agents write more test scenarios than they otherwise would, some of which are thin. We consider thin scenarios better than absent ones and have not tried to quantify the trade.

What we are buying with that is a repo whose history contains its own justifications. When a decision made six weeks ago turns out to be wrong, the question is not "what were we thinking" but a grep. The night shift leaves the kettle warm.

Why this is governance

The framing we keep returning to is that this is not observability tooling that happens to point at agents. It is a governance mechanism in the plain sense: a rule about what counts as finished work, plus an artifact that makes compliance with the rule checkable after the fact by someone who was not there.

Guidance on building effective agents tends to emphasize keeping systems simple and transparent about the steps being taken. Trajectory logging is the version of that transparency which survives the session. The agent's context window is gone at the end of the run. The reasoning log is not, and it is the only thing at the end of the run that can be asked what it was standing on.

A fleet of agent-run repos does not scale on the quality of any single agent's output. It scales on whether a later reader, human or agent, can tell a grounded claim from an ungrounded one without redoing the work. Four values in a field is a small mechanism for that. It is the smallest one we found that does anything at all.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-21: enrich grounding-has-four-values: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 8670