Working with AI
How to read the checkpoints your AI agent leaves
Everything below comes from one real sprint: adding localStorage persistence to a small todo app in a sandbox. This is the actual review checkpoint the sprint saved, and how to read it without being an engineer.
{
"phase": "review",
"summary": {
"verdict": "approve",
"files_changed": 2,
"files_planned": 2,
"blocking": 0,
"should_fix": 1,
"nitpicks": 0,
"positive": 1
},
"scope_drift": { "status": "clean", "extra_files": [] },
"findings": [
{
"severity": "should_fix",
"file": "app.js",
"line": 31,
"description": "JSON.parse on corrupted storage throws and blanks the list",
"resolution": "wrapped in try/catch, falls back to empty list"
},
{
"severity": "positive",
"file": "app.js",
"description": "storage writes are debounced, no churn on fast typing"
}
],
"branch": "feat/persist-todos",
"integrity": "54a40087511e6fec...f816b6a8edf893"
}summary: the twenty-second read
Start here and you may be done. The verdict is approve, and files_changed: 2 against files_planned: 2 means the work touched exactly what the plan said it would. If those two numbers ever disagree, the next field explains how.
scope_drift: did it stay inside the agreement?
This is the field that does not exist in normal AI coding. status: "clean" with an empty extra_files list means nothing was built that you did not agree to. When an agent gets enthusiastic, this is where it shows: status: "drift" and a list of files nobody planned. You then decide whether the extras stay. The point is that you decide, because the comparison is automatic.
findings: problems with their fixes attached
The first finding is a real class of bug: if the saved data ever got corrupted, the app would crash on load and show an empty list. Three things to notice about how it is recorded. It has a severity (should_fix, not blocking: the feature works, this is robustness). It has an exact location (app.js, line 31), so nothing is vague. And it has a resolution, because in a sprint, findings get fixed while the agent still has context, not filed in a backlog. A checkpoint full of findings is not a bad sign. A checkpoint with findings and no resolutions is.
The second finding has severity positive. Reviews record what was done well too, not because it is polite, but because "keep doing this" is information the next sprint can use.
integrity: why you can trust the file at all
The last field is a SHA-256 hash of the checkpoint itself. If anyone, including the agent, edits this file after it was saved, the hash stops matching and every downstream consumer treats the artifact as untrusted. The phase gate that decides whether a commit can proceed reads these files with verification on. So the chain you are trusting is not "the agent says the review passed". It is: a review artifact exists, has the required fields, and has not been touched since the review wrote it.
Where to find yours
Checkpoints live under .nanostack/ in your project, one folder per phase, one JSON file per run. Two ways to read them: open the file (it is just JSON, like the one above), or render it as a local page with bin/render-artifact.sh review. The sprint also writes a journal in plain markdown under .nanostack/know-how/journal/, which reads like a short report: what was built, what was found, what passed.
The habit that makes all of this useful takes one minute: after each sprint, read the summary, glance at scope_drift, and skim the findings. If those three look right, the work earned its merge.