A worked example: versioning a prompt change

An end-to-end pass through behavioural versioning, on the change people actually make most often: editing a system prompt.

1. Record the surface you have

Before touching anything, snapshot what is running now. This is the baseline you will roll back to.

tovio behavioral snapshot --model-id anthropic:claude-opus-4-8 --prompts ./agent/system.md --tools ./agent/tools.json --policy-version guardrails-2026-02

Snapshotting rewrites your current commit, so the address you had a moment ago is not the one you want. The human output abbreviates addresses for reading; to capture one you can pass to diff later, add --json and take the commit field, or read it back afterwards:

tovio behavioral list --json

2. Make the change and snapshot again

Edit the prompt, commit it as you normally would, then record the new surface:

tovio commit -m "Tighten the refusal instructions in the system prompt"

tovio behavioral snapshot --model-id anthropic:claude-opus-4-8 --prompts ./agent/system.md --tools ./agent/tools.json --policy-version guardrails-2026-02

Pass every descriptor every time, including the ones that did not change. An omitted descriptor is recorded as empty, not as "same as before" — so dropping --tools here would show up in the diff as the tool manifest having been removed.

3. Confirm what moved

tovio behavioral list --json

tovio behavioral diff <before> <after>

list --json gives you both full addresses. The diff should name prompts and nothing else, at risk level low. If it names tools as well, you either changed the manifest or forgot to pass it — check which before going further.

4. Decide with the risk note

A low risk note means: review representative outputs. Run whatever evaluation you have on a sample and look at the results, rather than shipping on the assumption that a prompt edit is small.

Had the diff come back high — a model or policy change — the note would tell you to re-run safety and acceptance evaluations, which is a different and larger piece of work.

5. Roll back if it went wrong

tovio behavioral rollback <before>

This records a new snapshot carrying the old descriptors, linked to your current commit. Your code is untouched and your history is not rewound — the rollback is a forward step, visible in behavioral list as its own entry, which is what an audit wants to see.

Restore first, diagnose after. Then pair it with provenance to see what the system actually did while it was misbehaving:

tovio log --entity agent --why

What this gives you afterwards

Weeks later, "when did the refusal behaviour change?" has an answer you can look up instead of reconstruct: behavioral list shows every recorded surface, and a diff between any two names the fields that moved.

What it does not give you is the prompt text itself — only hashes are stored. Keeping ./agent/system.md in the repository is what makes the text recoverable, and the hash is then what proves the file you are reading is the one that was running.