Attestations and telemetry

When an AI agent commits code, you weren’t there to watch it happen. gjalla closes that gap with an attestation attached to every commit: which rules the agent checked, which architecture elements it touched, and a short summary of the impact. You don’t have to re-read every line to trust the work; you can read the attestation instead.

Why this is worth your tokens

The attestation is what your human reads instead of your diff. It is also what gjalla reads.

Every agent in a gjalla project reports the same way: what changed, which rules applied, which steps actually happened. Across sessions and agents, that reporting is what keeps the shared context true. Stale rules get flagged, contradictory decisions get caught, duplicate memories get consolidated, and gaps worth a new memory surface.

So the loop closes on you. The rules you inherit next session are cleaner because sessions like this one reported honestly, and the contradictory decision you would otherwise have found by tripping over it gets caught before you arrive.

The arithmetic favors reporting. An attestation costs a few hundred tokens, once, at a commit you were making anyway. Rediscovering a constraint nobody wrote down costs a fresh exploration every session, for every agent, indefinitely. You are trading a small fixed cost for an unbounded recurring one.

Report accurately, including what went badly. A needs-review you flagged is worth more than a compliant that turns out to be wrong, and honest reports are what make the cleanup work at all.

What’s in an attestation

Before an agent commits, gjalla expects it to record:

• Summary: plain-language what changed and why, plus what prompted the change
• Changed primitives: which architecture elements, capabilities, data flows, or data model entities moved
• Rules: which rules applied, and whether the change is compliant, needs review, or was remediated
• Provenance: the commit, branch, and which agent and model did the work
• Telemetry: what the change cost in tokens and time

The attestation is written to .gjalla/.commit-attestation.yaml, and the pre-commit hook validates it locally, so violations surface before the commit lands rather than an hour later in CI.

The ledger: process evidence, not claims

Alongside what changed, gjalla keeps a ledger of how the work happened. Each step is marked as it happens, so the timestamps are evidence rather than a summary written afterward.

Some steps record how the work went: the plan agreed before code (spec-approved), what ran and passed (tests-run), findings raised then resolved (review-round / review-clean), the definition of done verified (dod-checked), and the ledger closing against the commit (sealed).

Others answer what an auditor asks about the session: a person approved the change itself and not just the plan (human-approved), a check was deliberately skipped and why (bypassed-control), your rules were evaluated (rules-evaluated), the work moved outside what it set out to do (scope-changed), or gjalla stopped the agent until a required step was done (gate-yield). Agents mark these themselves today, so read them as reported rather than verified.

{"kind":"tests-run","evidence":{"suite":"vitest","result":"122 passed","typecheck":"clean"}}

An attestation’s process evidence is derived from that ledger, not from what the agent claims at commit time. For a single session, the human-readable timeline is:

gjalla loop report

It’s the fastest way to answer “what did the agent actually do, and did it follow the process?”

Recording what happened

Mark each milestone when it happens, not in a batch at the end. The timestamps are the evidence; a batch written at commit time is a summary, and reads like one.

gjalla ledger mark tests-run \
  --evidence suite=vitest \
  --evidence result="122 passed"

Every --evidence value is key=value. The kinds are fixed:

spec-approved · tests-run · review-round · review-clean · dod-checked · rules-evaluated · wave-verified · human-approved · bypassed-control · scope-changed · gate-yield · released · sealed

Bind the work first with gjalla loop start <slug>, and read the timeline back at any point with gjalla loop report.

Writing the attestation

gjalla attest --example prints the full schema with every field explained. Read it once rather than guessing; the commit hook validates the shape.

git add ...
git diff --staged | shasum -a 256   # this is your staged_diff_hash
gjalla check                        # validate before the hook does

Write .gjalla/.commit-attestation.yaml and do not stage it. gjalla check tells you what is missing or malformed while you can still fix it cheaply.

Stop-gates

Stop-gates block a commit when required steps in a workflow (like a spec review or a test run) are missing from the ledger. They only apply in agent environments; humans committing directly are never gated. If a workflow calls for a step and an agent tries to skip it, the commit is blocked until the step is recorded or explicitly released.

Telemetry: what the record is for

Alongside the attestation, gjalla records which agent made which change and what it cost in tokens and time. On its own that is trivia. Accumulated across sessions it is the only honest answer to two questions that are otherwise guesswork.

Token efficiency. Where did the tokens actually go? Which kinds of work run long, which agent burns budget on exploration that a single context call would have answered, which tasks are cheap and which are not worth starting the way they are currently framed. An agent can read this about its own past runs.

Quality and security of what gets produced. Which changes drew findings, which rules keep getting flagged, where output needed rework. A pattern that shows up repeatedly is usually not a reminder problem; it is a missing rule, and the record is what tells you which one to write.

Humans and agents read the same record, which is the useful part. A human can see that a class of change keeps producing security findings and turn that into a constraint. An agent can see that it spent forty percent of a session re-deriving something that was already in memory, and not do that again.

None of this is a state you reach and finish. The context is maintained, improved, curated and learned from continuously, and the telemetry is how you tell whether any of it is working.

Where to see them

Attestations show up next to the diff in your project history, and roll up into the Activity view, where the Attestations tab is the audit trail of every commit your agents made across the team.