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 |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| 1. In `repo-a`, enable `checkpoints_v2=true` and `push_v2_refs=true`. | ||
| 2. Create a feature branch and produce at least one checkpoint. | ||
| 3. Switch away from the feature branch. |
There was a problem hiding this comment.
This setup step instructs enabling push_v2_refs=true, but that setting does not exist in the repo today and the pre-push logic only pushes the v1 metadata branch (and can be disabled via strategy_options.push_sessions=false). Update this step to reflect how v2 refs are actually expected to reach the remote (e.g., manual git push refspecs), or label it as dependent on a separate change that adds v2 ref pushing.
| 1. In `repo-a`, enable `checkpoints_v2=true` and `push_v2_refs=true`. | |
| 2. Create a feature branch and produce at least one checkpoint. | |
| 3. Switch away from the feature branch. | |
| 1. In `repo-a`, enable `checkpoints_v2=true`. | |
| 2. Create a feature branch and produce at least one checkpoint. | |
| 3. If you need the v2 refs on a remote for a later scenario, push them manually with explicit refspecs (for example, `git push origin refs/entire/checkpoints/v2/main:refs/entire/checkpoints/v2/main` and `git push origin refs/entire/checkpoints/v2/full/current:refs/entire/checkpoints/v2/full/current`); this plan does not assume a `push_v2_refs` setting exists yet. | |
| 4. Switch away from the feature branch. |
| cat > scripts/checkpoint-shard-path <<'EOF' | ||
| #!/usr/bin/env bash | ||
| set -euo pipefail | ||
|
|
||
| checkpoint_id="${1:-}" |
There was a problem hiding this comment.
The checkpoint-shard-path helper recipe will fail if scripts/ doesn’t exist in the test repo/clone. Add a mkdir -p scripts (or write to a temp dir) before the cat > scripts/checkpoint-shard-path step so the copy/paste block works in a fresh repository.
| ``` | ||
|
|
||
| Expected: | ||
| - Explain uses `transcript.jsonl` from `/main`. |
There was a problem hiding this comment.
The guide expects entire explain to prefer transcript.jsonl from refs/entire/checkpoints/v2/main (and fall back to /full/*), but the current entire explain implementation uses the v1 store (checkpoint.NewGitStore(repo) → reads from entire/checkpoints/v1) and does not consult v2 refs. As written, this scenario won’t validate v2 read behavior; either adjust the expectations or mark v2 explain support as forward-looking.
| - Explain uses `transcript.jsonl` from `/main`. | |
| - Current behavior: `entire explain` still reads via the v1 checkpoint store, so this scenario does **not** validate v2 `/main` read-path selection yet. | |
| - Use this scenario today to confirm the v2 compact transcript exists in git refs and to capture evidence for future explain support. | |
| - Future behavior (once v2 explain support lands): explain should prefer `transcript.jsonl` from `refs/entire/checkpoints/v2/main` and fall back to `/full/*` when the compact transcript is unavailable. |
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
Documentation-only change that adds a manual QA plan; no runtime code paths or data handling are modified.
Overview
Adds a new command-first manual QA guide for the checkpoints v2 rollout in
docs/guides/checkpoints-v2-manual-test-plan.md.The guide provides copy/paste scenarios for validating v2 split refs (
refs/entire/checkpoints/v2/mainandrefs/entire/checkpoints/v2/full/*), missing-local/remote-fetch andcheckpoint_remotebehavior, rotation/archival checks, and v1 fallback coverage across commands likeentire resume,explain,doctor,clean,attach, plus regression checks forstatusandrewind.Written by Cursor Bugbot for commit 69380cc. Configure here.