Checkpoint Version Management and Persistence

Using brainstorming because this is a feature design request, and using-entire because the plan needs to be grounded in this repo’s checkpoint history rather than guessed from code shape. I’ll first read the issue and relevant local code, then I’ll ask one clarifying question at a time before proposing the design.

I’m pulling the issue through GitHub’s API so I can see the body and comments, then I’ll map it onto the checkpoint storage path in the local repo. In parallel I’m checking the worktree and whether Entire checkpoint history is available for the files we’re about to reason about.

The issue has no comments, so the proposal content is all in the issue body. Key detail for this task: the issue names cli_version plus a checkpoint storage format field, but your requested field name is checkpoint_version; I’ll treat that naming mismatch as the first design point to clarify after I inspect the current metadata shape.

The first broad search was too noisy, so I’m narrowing to the write/read structs and the condensation path that actually creates committed checkpoint metadata. Recent commits show this area was just refactored around checkpoint store boundaries, so I’m also checking whether those commits carry Entire checkpoint trailers before I rely on inferred intent.

Checkpoint history is present for the recent store-boundary changes. I’m reading those summaries next because the issue explicitly says this work should not introduce a second abstraction that fights the ongoing checkpoint-store refactor.

Two checkpoint summaries came back quickly and confirm the store-interface direction: callers should target committed reader/writer interfaces rather than hard-coding the concrete Git store. One older explain call is still running; I’ll stop it if it doesn’t return promptly so it doesn’t block the design pass.

The missing checkpoint for 957b03f1f773 means I won’t treat that commit’s intent as recorded history. For the rest, I’ll label store-boundary notes as checkpoint-backed and the metadata field placement as source-inferred after reading the structs and write path.

Source inference so far: both root CheckpointSummary and per-session CommittedMetadata already have cli_version, and new checkpoints get those fields in writeCheckpointSummary plus writeSessionToSubdirectory. The smallest compatible change is likely a new field on the root summary, written in the same place, with read-time defaulting where summaries are loaded.

The store boundary already supports the future rollout via CommittedRefs and a single committed Write(ctx, req) surface, so this change should avoid adding config or store modes. I’m checking the ref resolution code only to make sure the proposed default value (branch-v1) lines up with the current branch-backed topology.

There is already a deliberately inert settings test for strategy_options.checkpoints_version, which supports keeping this change metadata-only for now. I’m avoiding a design that wires settings into behavior yet, because the proposal says rollout control is separate and you explicitly called repo-wide settings out as later work.

The current docs still show an older combined Store shape, while code has split CommittedStore/TemporaryStore plus Writer. I’ll account for that in the design: any doc update should be narrowly around the metadata example, not a broad architecture cleanup unless the implementation step requires it.

I read issue #1471 and the relevant checkpoint metadata path. One naming mismatch matters before design: the issue says checkpoints_version, while your request says checkpoint_version.

Which JSON key do you want: exactly checkpoint_version, or issue-aligned checkpoints_version?

checkpoint_version makes sense, and I’ll align the design around that.

One more scope question: should this field live only on the root checkpoint metadata.json (CheckpointSummary), not the per-session 0/metadata.json files?

That matches the current structure: root CheckpointSummary owns checkpoint-wide facts, while 0/metadata.json, 1/metadata.json, etc. are session-specific.

Do you want the literal version value to be exactly branch-v1 for the current entire/checkpoints/v1 storage format?

I’d use branch-v1.

Alternatives:

• branch-v1: Best fit. Communicates “branch-backed checkpoint format, version 1” and leaves refs-v1 free for the first custom-ref format.
• v1-branch: Also clear, but it emphasizes version before storage kind. Later v1-refs reads a little less naturally.
• checkpoints-branch-v1: More explicit, but redundant because the field is already named checkpoint_version.
• metadata-branch-v1: Too narrow. The issue is about checkpoint storage format, not just metadata file shape.

My recommendation: root metadata gets "checkpoint_version": "branch-v1" for current entire/checkpoints/v1 checkpoints, and future custom-ref storage can start at "refs-v1" without implying it is a continuation of branch-backed v1.

Does branch-v1 feel like the right identifier?

Three viable approaches:

1. Root-only field on CheckpointSummary with read-time defaulting to branch-v1. This is the smallest coherent change. New root metadata.json writes include "checkpoint_version": "branch-v1", and any old root metadata read through the checkpoint package is normalized to branch-v1 in memory.

2. Root field plus a WriteCommittedOptions field. More flexible, but unnecessary right now because storage mode is not configurable yet. It adds a caller-facing concept before there is more than one valid value.

3. Root field on both root and session metadata. I would avoid this. You already called out the right model: all sessions under a checkpoint share the checkpoint storage format, so session-level duplication can drift.

Recommendation: approach 1.

Design Add a package-level constant in checkpoint, likely CheckpointVersionBranchV1 = "branch-v1" or an unexported constant if only internal tests need it. Add CheckpointVersion string 'json:"checkpoint_version,omitempty"' to CheckpointSummary, not CommittedMetadata.

Write path: writeCheckpointSummary sets CheckpointVersion: CheckpointVersionBranchV1 for all newly written root metadata. UpdateCheckpointSummary preserves the existing field when rewriting root metadata for attribution, and if it reads old metadata without the field, it should normalize before writing so the update also backfills it.

Read path: normalize CheckpointSummary after JSON unmarshal in ReadCommitted, and probably centralize that in a small method/helper so readSummaryFromBlob and direct tree reads do not each invent their own behavior. Missing or empty means branch-v1; explicit values are preserved for future refs-v1.

Tests: add focused checkpoint package tests for new writes including the field, old metadata reading as branch-v1, and update/backfill preserving or filling the version. Update the docs root metadata example to show checkpoint_version.

Does this design look right?

I’ll write the approved design into a local spec file now. I won’t commit it yet because the repo instructions require explicit commit approval, even though the brainstorming workflow normally commits the spec.

The spec file is written. I’m doing the required self-review pass now: checking for placeholders, contradictions, unclear scope, and whether the design still stays within the issue’s metadata-only slice.

The spec self-review found no placeholders or scope drift. git status is not showing the new file, so I’m checking whether docs/superpowers/ is intentionally ignored before I ask you to review it.

Spec written at 2026-06-22-checkpoint-version-design.md.

I did not commit it: docs/superpowers is ignored by this repo, and repo instructions require explicit approval before commits or force-adding ignored files. Please review the spec and tell me if you want changes before I move on to the implementation plan.

Using writing-plans now because the design is approved and the brainstorming workflow’s next step is an implementation plan, not code edits yet.

I’m using the writing-plans skill to create the implementation plan. I’ll read the nearby tests before writing it so the plan is precise about which tests to add and how to run them.

The nearby tests already have helpers for reading root metadata from the metadata branch and exercising BackfillAttribution, so the plan can stay small and avoid new harness code. I’m writing the implementation plan now under the same ignored docs/superpowers area.

The implementation plan will use one review checkpoint: the change touches an exported metadata type, but the actual diff is a single behavior unit, so splitting code/tests/docs into separate commits would make the history less coherent. I’ll make that explicit at the top of the plan.

I’m about to add the plan file only. No production files or tests are being edited yet, so this remains at the planning gate.

The plan is written. I’m doing the plan self-review now and tightening anything vague before handing it back.

The plan self-review is complete: no placeholder markers remain, the plan maps every spec requirement to a task, and the tests cover both new writes and legacy reads/updates. The plan file is also under the ignored docs/superpowers directory, same as the spec.

Plan complete and saved to 2026-06-22-checkpoint-version.md.

It declares step-by-step execution with one review checkpoint and one planned commit: checkpoint: record branch checkpoint version.

Two execution options:

1. Inline Execution - I implement the plan in this session, then pause at the review checkpoint.
2. Subagent-Driven - I dispatch the implementation task to a fresh subagent, then review the result here.

Which approach?

Using executing-plans for inline implementation. I’ll follow the approved plan task-by-task, write the tests first, run the expected failing check, implement the minimal change, verify, then pause at the review checkpoint without committing.

I’m using the executing-plans skill to implement this plan. Since you chose inline execution, I’ll keep the work in this session rather than dispatching a subagent.

I reviewed the plan against the current files and don’t see a blocker. I’m starting with the red tests for new writes, legacy defaulting, and summary update behavior before touching production code.

I’m editing the checkpoint package tests now. These tests intentionally refer to the new field and constant before they exist so the next focused test run should fail for the expected reason.

The tests are in place. I’m running only the four new tests now; the expected result at this point is a compile failure for the new field/constant.

The focused test failed for the expected reason: CheckpointVersion and CheckpointVersionBranchV1 do not exist yet. I’m adding the root metadata field, defaulting helper, and write/read normalization now.

The production normalization is in place. I’m updating the architecture example narrowly so it documents the new root-only field without taking on the stale interface section nearby.

The docs example is updated. I’m formatting the touched Go files and then I’ll run the focused test set from the plan followed by the checkpoint package tests.

gofmt completed with exit status 0. Now I’m running the focused tests that cover the new field, legacy defaulting, update preservation, and the existing write dispatcher path.

The focused checkpoint version tests passed: go test ./cmd/entire/cli/checkpoint -run '...' -count=1 exited 0. I’m running the full checkpoint package tests next, which is still scoped to the touched package.

The full checkpoint package test passed with exit status 0. The repo’s Go instructions also call for a relevant vet/build signal and lint after Go edits, so I’m adding those boundary checks before I present the diff.

go vet ./cmd/entire/cli/checkpoint exited 0, and mise run lint exited 0 with golangci-lint reporting 0 issues. I’m reviewing the exact diff now for scope before I pause for your checkpoint review.

The tracked diff matches the planned six files and stays scoped to root checkpoint version metadata. I’m doing the completion-verification pass now before I summarize the checkpoint.

I’ve read the verification checklist and I’m adding one final diff hygiene check. No code has changed since the package tests, vet, and lint ran.

Implemented the review checkpoint, no commit made.

Changed:

• Added root checkpoint_version on CheckpointSummary.
• New checkpoints write branch-v1.
• Legacy root metadata with a missing version normalizes to branch-v1 on read.
• Summary update/backfill preserves explicit future values like refs-v1 and backfills legacy missing values.
• Updated the root metadata docs example.

Verification evidence:

• Expected red test first failed with undefined CheckpointVersion / CheckpointVersionBranchV1.
• gofmt -w ... exited 0.
• go test ./cmd/entire/cli/checkpoint -run 'TestWriteCommittedWritesBranchCheckpointVersion|TestReadCommittedDefaultsLegacyCheckpointVersion|TestUpdateCheckpointSummaryBackfillsLegacyCheckpointVersion|TestUpdateCheckpointSummaryPreservesExplicitCheckpointVersion|TestWrite_DispatchesEachRequest' -count=1 exited 0.
• go test ./cmd/entire/cli/checkpoint -count=1 exited 0.
• go vet ./cmd/entire/cli/checkpoint exited 0.
• mise run lint exited 0, golangci-lint reported 0 issues.
• git diff --check exited 0.

Diff is six tracked files: checkpoint.go, committed.go, committed_reader_resolve.go, committed_update_test.go, committed_write_test.go, and docs/architecture/sessions-and-checkpoints.md.

Please review the diff. If it looks good, say commit and continue or approve the commit explicitly.

I’ll commit only the tracked implementation/docs diff from the checkpoint review. Before staging, I’m re-reading status and the scoped diff summary so the commit contains exactly the reviewed files.

git diff --check exited 0, and the status shows only the six reviewed tracked files. I’m creating the approved commit now with the planned subject and body.

The commit was created successfully. I’m checking HEAD and tracked working-tree status now; since the file contents did not change after the verification runs, those results remain valid from the review checkpoint.

There are no remaining implementation tasks in the approved plan after this commit. I’m checking the completion-review skill availability now because this is the point where it would normally be used before handing work back.

The completion-review skill is available and this is a natural checkpoint after executing the plan. I’ll run a focused code-review subagent against the single commit, then verify any findings against source before deciding whether changes are needed.

Committed as fdb35e5146 checkpoint: record branch checkpoint version.

Post-commit checks:

• git status --short --branch shows a clean tracked worktree on feat/checkpoint-version-metadata.
• git show --stat --oneline HEAD shows the expected 6 files and 175 insertions(+), 3 deletions(-).

The prior verification remains valid because no file content changed after it: focused checkpoint tests, full checkpoint package tests, go vet ./cmd/entire/cli/checkpoint, mise run lint, and git diff --check all exited 0.

No remaining implementation steps in the approved plan. The ignored docs/superpowers/... spec/plan files were not committed.

Using using-entire for this validation because it’s a codebase-understanding question about checkpoint metadata behavior. I’ll verify from source and tests, and distinguish code facts from inferred behavior.

I’m checking the concrete write paths now: the root summary writer, the session metadata writer, and any tests or docs that pin cli_version.

The search already shows both metadata structs have CLIVersion and the committed writer assigns versioninfo.Version in two places. I’m reading those exact ranges and the existing regression test so I can give you a precise answer.

There is already a dedicated regression test for this exact behavior. I’m running just that test now to validate the implementation is active rather than only present in structs.

The focused cli_version test passed with exit status 0. I’m grabbing line-numbered references for the exact struct fields, write assignments, and test assertions so the answer is easy to audit.

Yes. Source-verified, not just inferred.

For committed checkpoints, cli_version is already:

• Defined on session metadata: checkpoint.go
• Defined on root checkpoint summary: checkpoint.go
• Populated on session metadata.json with versioninfo.Version: committed.go
• Populated on root metadata.json with versioninfo.Version: committed.go

There is also a dedicated regression test, TestWriteCommitted_CLIVersionField, that writes a checkpoint and asserts both root CheckpointSummary.CLIVersion and session CommittedMetadata.CLIVersion equal versioninfo.Version: checkpoint_test.go.

I ran:

Exit status 0:

So yes: for newly written committed checkpoints, cli_version is already implemented and actively populated in both root and session metadata.

Using pfleidi:review for the branch review against origin/main. I’ll fetch/update the remote-tracking ref, build the review context, launch the required parallel review agents, verify any findings myself, and only fix high-confidence Required findings by default.

I’m refreshing origin/main and collecting the review surface. The review skill requires git diff origin/main directly, so this may include all branch-only committed and uncommitted changes in one pass.

git fetch origin main completed. gh pr view could not resolve a GitHub PR from this remote, so I’ll mark PR context as unavailable/no PR found and continue.

Review surface: 6 changed files, all in checkpoint metadata code/tests plus the sessions/checkpoints doc. Context table before agents:

I’m launching the five required first-pass reviewers now because this is a Go diff.

The first-pass reviewers are running. While they work, I’m doing my own lightweight source check over the changed paths so I can verify or reject any findings quickly when they return.

My initial pass found the changes are tightly scoped: one new constant, one root summary field, normalization at summary read boundaries, and tests simulating legacy/future metadata. I’m waiting for the first-pass reviewers to finish before launching the independent coverage sweep.

Security review returned clean. I’m continuing to wait on the correctness, simplification, readability, and clean-Go agents.

Correctness found one concrete issue: WriteCommitted can rewrite an existing checkpoint root summary and currently hard-codes branch-v1, which may clobber an explicit future version. I’ll verify that against source after all agents finish.

Clean-Go independently confirmed the same issue. I’m waiting on the remaining simplification and readability passes, then I’ll run the required independent coverage sweep.

Simplification confirmed the same write-path preservation issue. One first-pass reviewer remains.

All first-pass reviewers are in. Three agents found the same Required issue; security/readability found none. I’m launching the independent coverage sweep now without passing it the first-pass findings.

While the coverage pass runs, I’m verifying the reported issue directly against the current source and the WriteCommitted flow.

The reported issue is source-backed: writeStandardCheckpointEntries reads an existing summary, then writeCheckpointSummary reads the root summary again for other root fields but still writes CheckpointVersionBranchV1. That means a second session write can overwrite an explicit future version.

The independent coverage sweep also found the same Required issue and no separate findings. Before fixing it, I’m applying the code-review-receipt workflow so I don’t blindly accept or overcorrect the feedback.

I verified the finding against the actual flow: WriteCommitted rebuilds root metadata on repeated checkpoint writes, and writeCheckpointSummary currently preserves attribution/review flags but not CheckpointVersion. That violates the stated intent to preserve explicit future values.

Required

No improvement-only findings were reported.

Planned Autofix

I’m applying that minimal fix now; no commit will be made.

./tmp/ exists and is ignored, so I’m creating the review ledger there before editing, per the review workflow.

I’m adding a focused regression test first. It will set raw root metadata to refs-v1, perform another WriteCommitted, and assert the raw root value stays refs-v1.

I’m editing only the test file for the regression first, then I’ll run that one test to confirm it fails for the issue the reviewers found.

The regression test is added. I’m running just that test now; it should fail before the production fix because the write path still hard-codes branch-v1.

The regression fails exactly as expected: raw checkpoint_version becomes "branch-v1" instead of preserving "refs-v1". I’m making the minimal production change now in writeCheckpointSummary.

The write path now carries the existing normalized version forward. I’m formatting the two touched Go files and rerunning the new regression test.

The new regression test now passes. I’m running the scoped verification set for this review fix: checkpoint package tests, vet, lint, and diff whitespace check.

All scoped verification commands exited 0. I’m updating the review ledger and checking the final diff before reporting the review result.

The ledger is updated. I’m reading the final diff stat and exact changed hunks for the autofix now.

The autofix diff is limited to the reported issue: one carry-forward variable and one regression test. I’m closing the completed review agents now.

Review completed and the single Required finding was fixed. No commit was made.

Results

Verification

Traceability

Ledger: tmp/pfleidi-review/review-cli-20260622-110207.md

Review summary: 1 Required finding, fixed. 0 improvement-only findings. Working tree has the two autofix files modified and is verification-clean.

I’ll commit only the review autofix diff. First I’m rechecking status and the scoped diff so the commit does not accidentally include anything outside the two fixed files.

The diff is exactly the reviewed autofix, and git diff --check exited 0. The focused tests, full checkpoint package tests, vet, and lint are still valid from the review fix because no file content changed after those runs. I’m creating the approved commit now.

The review-fix commit was created. I’m checking HEAD and working-tree status now; if there is nothing else in scope, I’ll hand back the branch state.

Committed as f45406bbea checkpoint: preserve checkpoint version on rewrite.

Branch now has two commits over origin/main:

• f45406bbea checkpoint: preserve checkpoint version on rewrite
• fdb35e5146 checkpoint: record branch checkpoint version

git status --short --branch shows no tracked working-tree changes. Prior review-fix verification remains valid: focused checkpoint tests, full checkpoint package tests, go vet, mise run lint, and git diff --check all exited 0 before the commit, with no content changes afterward.

No remaining implementation or review steps are pending.

Using pfleidi:pr to prepare and open a draft PR for the current branch. I’ll follow its workflow: scope check against origin/main, sync, discover/deduplicate verification, run checks, push, then create the PR.

I’m starting the PR scope check against origin/main using the merge-base path required by the PR workflow. If the branch contains anything outside checkpoint-version metadata, I’ll stop before pushing.

Merge base is 77cba9fc4ef5908403d64f5511260ce33507c133. I’m reading the branch commits and changed-file list from that base now.

Scope check: 6 changed files, all related to checkpoint metadata versioning; commits are the two checkpoint-version commits. Working tree is clean, so I’m syncing with origin/main now.

Fetch completed. I’m merging origin/main into the branch per the PR workflow; this writes Git metadata, so it needs elevated git access.

git merge origin/main reported “Already up to date.” I’m checking the verification-command cache location and then I’ll inspect the project’s documented verification sources.

tmp/ exists and is ignored, but there is no PR verification cache yet. I’m creating tmp/pfleidi-pr/ and doing normal discovery from mise, CI, README, and manifests.

I’m locating the verification source files first, then I’ll read only the relevant sections instead of running every discovered command.

The first file scan missed hidden config by default, so I’m repeating with hidden files included to catch .mise.toml and CI workflows.

I found CI workflows, README, and go.mod; there is no tracked Makefile or .mise.toml from the scan. I’m reading the README development/testing sections and CI/lint workflow definitions.

The README documents mise run build, mise run test, mise run test:integration, mise run test:ci, mise run lint, and mise run fmt; CI uses mise run test:ci:core, sharded integration, canary e2e, and mise run lint. I’m reading the mise task files directly so I can deduplicate instead of running aggregate and subtasks together.

The command discovery sources point to build, lint, unit/core tests, integration shards, and canary E2E. I’m reading the task recipes to select the smallest non-duplicative local PR checks.

There is no mise-tasks/test/_default file at that path, so I’m listing the test task tree and reading the actual default test recipe.

The lint task includes subchecks including gofmt, go mod tidy, shellcheck, and golangci-lint. CI additionally runs core tests, integration shards, and canary E2E; for this checkpoint package metadata change, I’ll use the local build/lint/core-test coverage and not run CI-only shard/e2e jobs unless needed.

I have the PR workflow in progress. Scope and sync are already checked; I’m finishing the verification selection now so the local checks match the repo’s CI without running duplicate or costly jobs.

I’m refreshing the skill instructions from disk after the context handoff so I don’t drift from its exact PR flow.

The skill confirms the next step is a deduplicated local verification plan, then push and draft PR creation if the tree stays clean. I’m checking current branch state once before running the selected commands.

The working tree is clean and the branch scope is still just checkpoint metadata code, tests, and the architecture doc. I’m going to cache the verification discovery in the ignored tmp/pfleidi-pr directory before running checks.

I selected one command per coverage area: lint/static via the documented lint task, build via the documented build task, and CI core tests via the CI task. I’m skipping the integration shards and e2e canary locally because this PR does not touch those surfaces and CI covers them.

Starting verification with the mutating command first. mise run lint can run auto-fixers/tidy checks in this repo, so I’m keeping it separate before build and tests.

Lint completed without reported issues. I’m checking whether it changed the tree before running the read-only build and test commands.

The tree stayed clean after lint. I’m running the independent build and CI core test commands in parallel now.

Build exited successfully. The CI core test command is still running, so I’m waiting on that process before deciding whether anything needs fixing.

mise run test:ci:core failed in strategy tests because subprocess git segfaulted during test setup/ref checks. Since this is a test failure, I’m switching into the debugging workflow before deciding whether it’s an environmental flake or something this branch caused.

The failing package is cmd/entire/cli/strategy, and both failures are subprocess git segmentation faults in temp repos. I’m reading those exact tests and rerunning only the failing cases with the same race/integration settings to see whether this is repeatable.

The two failed cases pass when rerun directly with the same tags and race flag. I’m now rerunning the whole strategy package to check whether the failure is a package-level intermittent crash rather than a deterministic failure in this branch.

The failing tests are not reproducible in focused or package reruns; the root cause points to an intermittent external git crash during the broad parallel test run, not this checkpoint-version change. Per the PR workflow, I’m rerunning the full selected verification plan from the top on the unchanged tree.

Lint passed again and did not change the tree. I’m rerunning build and CI core tests now.

Build passed on the rerun. The core test suite is still active; I’m waiting for the final exit status.

Verification after rerun:

The earlier test:ci:core run failed once from a subprocess git segmentation fault in strategy tests. The exact failed cases and the full strategy package both passed on focused reruns, and the complete selected plan passed after rerun.

The working tree is clean after verification, so there is nothing to commit. I’m checking whether the branch already has an upstream before pushing.

No upstream is configured, so I’m pushing with -u to publish the branch and set tracking.

The push is still running while it syncs the checkpoint metadata ref. I’m waiting for the final push status before creating the PR.

The branch is pushed and tracking origin/feat/checkpoint-version-metadata. I’m checking for an existing PR for this branch before creating a new draft.

No existing PR is open for this branch. I’m writing the PR body to an ignored temp file so gh pr create can use it without fragile shell quoting.

Creating the draft PR against entireio/cli now.

I’ll add the issue reference to the PR body and first check whether the interrupted gh pr create completed despite the abort.

The interrupted create did not leave a PR behind, and the tree is still clean. I’m adding a non-closing Refs #1471 line to the description, then I’ll create the draft PR.

Creating the draft PR with the updated body now.

gh pr create failed because this sandbox cannot reach api.github.com. I’m rerunning the same command with network approval.

gh needs the head/base specified because the repo remote is an entire:// mirror, not a GitHub URL. I’m retrying with the GitHub repo plus explicit --base main --head feat/checkpoint-version-metadata.

https://github.com/entireio/cli/pull/1494