Clarify checkpoints v2 rotation docs#1179
Conversation
Entire-Checkpoint: fb4beb223e3d
There was a problem hiding this comment.
Pull request overview
Adds an architecture note documenting how checkpoints v2 rotates /full/current into archived /full/<N> generations, how pending rotation publications are recorded locally, and how the pre-push path publishes archives + safely resets remote /full/current (including remote-rotation conflict recovery). Also updates an inline code comment to reflect the current pre-push stale-handoff dropping + queued-archive publication behavior.
Changes:
- Add
docs/architecture/checkpoints-v2-rotation.mddescribing v2 full-transcript generation layout, rotation, pending publication markers, pre-push publication, conflict recovery, and cleanup/failure windows. - Update rotation code comment to match current pre-push behavior around stale reset handoffs and publishing queued archives.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/architecture/checkpoints-v2-rotation.md | New architecture documentation for v2 full generation rotation + publication and recovery behavior. |
| cmd/entire/cli/checkpoint/v2_generation.go | Comment update describing how pre-push handles stale reset handoffs and queued archive publications. |
|
Bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 7026174. Configure here.
Correct the User A example to respect the 100-checkpoint rotation threshold, expand the pre-push step list with the idempotent short-circuit and the ancestor-check gate, clarify that the force-with-lease anchor is the remote hash just read (not the marker's previous_full_current_hash), note that the remote rotation conflict recovery path does mutate an archived ref, and correct the cleanup description to cover local ref deletion as well. Entire-Checkpoint: c6ba612414f1
Entire-Checkpoint: 453d4bb44f01
https://entire.io/gh/entireio/cli/trails/353
What
Documents how checkpoints v2 raw-transcript generations rotate, publish pending archives, and recover from remote rotation conflicts.
How
raw_transcriptfiles and that pre-push validates the newest queued reset root before publishing queued archive refs together.Verification
mise run buildmise run lintmise run testNote
Low Risk
Documentation-only changes plus a clarifying code comment; no functional behavior changes.
Overview
Adds a new architecture note
docs/architecture/checkpoints-v2-rotation.mddescribing how checkpoints v2 rotates/full/currentinto archived/full/<N>refs, how pending publication markers are used, and howpre-pushpublishes archives and safely resets remote/full/current.Clarifies the rotation comment in
v2_generation.goto reflect thatpre-pushdrops stale queued resets until the newest reset root is present in local/full/currenthistory, then publishes queued archive refs together.Reviewed by Cursor Bugbot for commit 7026174. Configure here.