docs: add command-first checkpoints v2 manual test guide#839
docs: add command-first checkpoints v2 manual test guide#839
Conversation
Entire-Checkpoint: f9f4c9654206
There was a problem hiding this comment.
Pull request overview
Adds a command-first manual QA guide for validating the “checkpoints v2” split-ref storage behavior and related workflows.
Changes:
- Introduces a new manual test plan doc covering
entire resume/explain/doctor/clean/migrate/status/rewind. - Adds shared Git inspection commands (refs, trees, archived generations) and a checkpoint shard-path helper recipe.
- Documents missing-local/remote-present and
checkpoint_remotescenarios.
Entire-Checkpoint: fc81cbd6d899
Entire-Checkpoint: c8f2b08cbc4c
Entire-Checkpoint: f5a5d8076f46
Entire-Checkpoint: 4ac0fc5b43c4
Entire-Checkpoint: ea6515ad2878
|
Bugbot run |
Entire-Checkpoint: 6b60ad4c5992
| Setup: | ||
| 1. Ensure repository has at least one commit. | ||
| 2. Ensure target session transcript exists on disk for the selected agent. | ||
| 3. Ensure latest commit does not already contain `Entire-Checkpoint` trailer. |
There was a problem hiding this comment.
Not a blocker, but just noting this last step is misleading/not necessary - it's possible for multiple untracked sessions to be added. Already having a trailer does not block new sessions from being attached.
| # Verify latest commit includes Entire-Checkpoint trailer | ||
| git log -1 --pretty=%B | ||
| # Verify checkpoint metadata exists on v1 branch | ||
| git show-ref --verify -- refs/heads/entire/checkpoints/v1 |
There was a problem hiding this comment.
This testing plan for attach seems to only cover regression testing for v1. I'm not so worried about v1: it's already been validated. I think we could run through this first scenario and that's fine if we want to regression test it.
Otherwise, the testing plan should cover that the attached sessions get added correctly to v2 refs.
|
|
||
| ## 3) `entire doctor` | ||
|
|
||
| - What it does: diagnoses and fixes disconnected `entire/checkpoints/v1` metadata branches and stuck sessions. |
There was a problem hiding this comment.
Is doctor intentionally unneeded + not supported in v2?
| - `--all` removes orphaned items and temporary files. | ||
| - `entire/checkpoints/v1` branch is preserved. | ||
|
|
||
| ### Scenario 4: Single-session cleanup (`--session`) |
There was a problem hiding this comment.
Is this necessary to test for checkpoints v2? I don't think we touched this at all, did we? I wonder if we can omit this section?
There was a problem hiding this comment.
Yes, I think we should omit that 👍
Entire-Checkpoint: 72379f04c132
Entire-Checkpoint: 4b9a7556e812
Entire-Checkpoint: 4bd79b175323
Entire-Checkpoint: 52a39b0356eb
Entire-Checkpoint: 844f7a5f83cd
|
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 0441abd. Configure here.
Summary
docs/guides/checkpoints-v2-manual-test-plan.md.entirecommand, with practical custom-ref workflows for missing-local/remote-fetch scenarios.Rendered Guide (Branch Link)
Note
Low Risk
Low risk documentation-only change; no runtime code paths or data handling are modified.
Overview
Adds a new
docs/guides/checkpoints-v2-manual-test-plan.mdcommand-first manual QA guide for the checkpoints v2 rollout.The guide documents v2 ref invariants and provides copy-paste setup/inspection steps and scenario-based validation for
entire resume,explain,doctor,clean,migrate(future),attach(future), and arewindregression check, including workflows to simulate missing-local/remote-present refs and collect evidence.Reviewed by Cursor Bugbot for commit 0441abd. Configure here.