Checkpoints vs. git commits
Every new user asks this within their first day: "Doesn't my git history already do this?"
Short answer: no, not for the thing checkpoints solve.
What a git commit is
A git commit is a content-addressed diff with a message. It records the bytes that changed and a freeform string describing the intent. The granularity is whatever you happened to git add and git commit, which in practice is dictated by mechanical things: PR-per-feature norms, squash-merge policy, CI cycle time, what felt like "enough" before lunch.
Commits are great at:
- Reproducing the codebase at any historical moment.
- Bisecting to find when a bug was introduced.
- Attribution (
git blame).
Commits are bad at:
- Explaining why the change was the right one.
- Aggregating multiple commits into a coherent unit of meaning.
- Recording what was intentionally not changed in the same slice.
- Surviving squash merges, force pushes, or rebases without information loss.
What a Kleio checkpoint is
A checkpoint is a claim about a slice of work: "I just shipped X, here's the validation status, here's what I deferred." It's tied to commits when relevant, but it's not derived from them.
Checkpoints are good at exactly the things commits are bad at:
- Explaining intent and validation status as first-class fields.
- Aggregating across N commits (and across human + agent authors).
- Recording the negative space — what's not in this slice and why.
- Surviving rewrites, because the checkpoint references the slice's meaning, not just its SHA.
How they relate
A checkpoint typically references one or more commits, and optionally closes one or more backlog items. The relationship is many-to-many in both directions, but the common case is "this checkpoint corresponds to the work in PR #N, which is these three commits."
When to log a checkpoint
A good rule of thumb: log a checkpoint when you'd be willing to write a one-paragraph PR description right now and have it stand up six weeks later.
Bad signal for a checkpoint:
- A formatting-only commit.
- A typo fix.
- A WIP push at the end of the day.
- A merge commit.
Good signal for a checkpoint:
- A feature slice that has tests passing and a clear "what shipped, what didn't" boundary.
- A non-trivial refactor, even one with no behavior change, where the why matters.
- A bug fix where the root cause and the fix are both worth recording.
Auto-closing backlog items
If a checkpoint references a backlog item explicitly (backlog_item_id), the item is closed. If a checkpoint mentions KL-42 in commit messages, or if the system detects a high-confidence semantic link (>= 0.90) between a merged PR and an open backlog item, the item is auto-closed and a link is recorded.
This is how the loop closes: capture during work → synthesize into a backlog item → ship a slice → checkpoint references the item → item closes with traceability back to the commit and the originating capture.
TL;DR
| Git commit | Kleio checkpoint | |
|---|---|---|
| Records | Bytes + freeform message | Intent, validation, deferred work |
| Granularity | Whatever you git add | A meaningful slice |
| Survives rebase / squash | Loses info | Yes |
| Cross-author aggregation | No | Yes |
| Closes backlog items | No | Yes (semantic + explicit) |
Use both. They answer different questions.