Add hidden checkpoint policy command#1508
Conversation
Store the repo checkpoint policy in a dedicated git ref and expose a hidden command for inspecting and updating it. The command syncs with the checkpoint remote before updates, rejects unsupported versions, and pushes only the policy ref. Entire-Checkpoint: b7feda2b129a
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| if err != nil && !errors.Is(err, errStopTraversal) { | ||
| return false | ||
| } | ||
| return found |
There was a problem hiding this comment.
Cancel during ancestry misclassified
Medium Severity
When the user cancels while isAncestorOf walks commit history, the helper returns false and drops the cancellation error. Sync then reports local-diverged instead of stopping cleanly, and updateBaseline can emit a false “diverges from remote” error even when local and remote share history.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit 4518d7b. Configure here.
There was a problem hiding this comment.
Pull request overview
Adds repository-level checkpoint policy storage and a hidden CLI surface to inspect/update it, without yet enforcing policy during hooks or checkpoint operations. This fits into the broader checkpoint format compatibility work by introducing a durable “policy ref” that later PRs can consult.
Changes:
- Registers a hidden
entire policycommand group with a visibleentire policy checkpointsubcommand for inspecting/updating policy state. - Introduces
checkpointpolicystorage + remote sync/update/push helpers forrefs/entire/policies/checkpoint(persisted aspolicy.jsonin commits). - Extends checkpoint format handling with ordering (
Compare) and explicit read/write support checks (CanRead/CanWrite), plus tests.
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| cmd/entire/cli/root.go | Registers the new hidden policy command group on the root command. |
| cmd/entire/cli/root_test.go | Adds coverage asserting the policy group is hidden while the checkpoint subcommand remains invokable. |
| cmd/entire/cli/policy_group.go | Implements the hidden policy group command and its git-repo precondition. |
| cmd/entire/cli/policy_checkpoint.go | Implements entire policy checkpoint inspect/update flow (sync vs update+push). |
| cmd/entire/cli/policy_checkpoint_test.go | Adds command-level tests for defaults, validation, downgrade behavior, push behavior, and cancellation silencing. |
| cmd/entire/cli/checkpointpolicy/update.go | Adds update logic with baseline selection, downgrade rejection, and policy validation. |
| cmd/entire/cli/checkpointpolicy/update_test.go | Adds tests for downgrade/force, local-ahead behavior, and divergence rejection. |
| cmd/entire/cli/checkpointpolicy/store.go | Adds local read/write for policy commits and ref management for refs/entire/policies/checkpoint. |
| cmd/entire/cli/checkpointpolicy/store_test.go | Adds tests for defaults, roundtrip read/write, malformed JSON, and preserving unsupported policy values on read. |
| cmd/entire/cli/checkpointpolicy/remote.go | Adds remote hash check, sync (fetch-on-diff), and push helpers for the policy ref. |
| cmd/entire/cli/checkpointpolicy/remote_test.go | Adds tests for sync behavior, divergence behavior, push rejection, and target resolution behavior. |
| cmd/entire/cli/checkpointpolicy/remote_internal_test.go | Adds unit tests for remote hash parsing. |
| cmd/entire/cli/checkpointpolicy/policy.go | Defines policy model/defaults/validation rules. |
| cmd/entire/cli/checkpointpolicy/policy_test.go | Adds tests for defaults and validation failures. |
| cmd/entire/cli/checkpointpolicy/format.go | Extends format parsing with family ranks, Compare, and write-support tracking. |
| cmd/entire/cli/checkpointpolicy/format_test.go | Updates tests to cover CanWrite, Compare, and string roundtrips. |
| fetched, err := fetchRemotePolicy(ctx, repo, target) | ||
| if err != nil { | ||
| return State{}, false, err | ||
| } | ||
| fetched.RemoteHash = remoteState.Hash | ||
| defer removeFetchRef(repo) | ||
| return fetched, true, nil |
Nest the checkpoint policy command under the checkpoint group and remove the hidden top-level policy group. This makes the development command path entire checkpoint policy while preserving the existing hidden status. Entire-Checkpoint: 21cc4b97e773
|
Bugbot run |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
There are 2 total unresolved issues (including 1 from previous review).
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit f3c10b3. Configure here.
| testutil.InitRepo(t, dir) | ||
| repo, err := git.PlainOpen(dir) | ||
| require.NoError(t, err) | ||
| return dir, repo |
There was a problem hiding this comment.
Missing git config isolation
Low Severity
New checkpointpolicy remote/update tests call Sync, Update, and Push, which shell out to git via checkpoint/remote using the process environment, but the shared repo fixture never calls testutil.IsolateGitConfigEnv. That can inherit a developer global git config and trigger flaky background git gc during t.TempDir() cleanup.
Additional Locations (1)
Triggered by learned rule: Tests shelling out to git CLI must call testutil.IsolateGitConfigEnv(t)
Reviewed by Cursor Bugbot for commit f3c10b3. Configure here.
Why
This is the second PR in the checkpoint-policy stack. It gives the repo a place to record the active checkpoint format and minimum required checkpoint format without turning that policy on in hooks or user command enforcement yet.
Stacked on #1507.
What changed
Adds a checkpoint policy model stored at
refs/entire/policies/checkpoint, plus sync/update/push helpers that resolve the same checkpoint remote used by checkpoint storage. Adds a hiddenentire checkpoint policycommand to inspect or update the policy.Usage examples
Inspect the effective policy:
Set the active checkpoint format written by the repo:
Set the minimum checkpoint format required by the repo:
Allow an intentional downgrade:
Decisions made during development
The command is hidden while the policy flow is still being split and reviewed.
The ref is singular and unversioned:
refs/entire/policies/checkpoint, matching thecheckpoint policycommand shape and avoiding another versioned custom ref name.Policy writes fetch the remote policy state first, evaluate downgrade and support checks against that state, update the local ref, then push only that policy ref.
The policy commit uses the existing checkpoint commit creation path, so signing follows the normal checkpoint commit signing setting when it is configured.
Technical tradeoffs
The policy reader accepts unsupported policy values so newer clients can publish future policy states without older clients corrupting or deleting them. Updates remain stricter: this CLI only allows setting versions it knows how to write or read.
Remote freshness is intentionally simple. The command compares the remote ref hash, fetches only when the hash differs, and avoids filesystem cache files or background refresh state.
Runtime enforcement is left out of this PR so reviewers can first inspect the policy storage and command surface independently.
Reviewer notes
This PR does not enforce the policy in hooks or user commands. That remains in the next stacked PR.
Note
Medium Risk
Policy updates push to the configured checkpoint remote and can change repo-wide format expectations, but the command is hidden and enforcement is not wired in yet.
Overview
Adds a checkpoint policy layer so repos can record which checkpoint format they write and the minimum format they require, stored at
refs/entire/policies/checkpointaspolicy.jsoncommits on a dedicated ref (not on normal branches).A new
checkpointpolicypackage handles read/write, remote sync (same checkpoint remote as checkpoint storage), updates with validation and downgrade guards (--forceto override), and push of only the policy ref. Format helpers gainCanWrite,Compare, and ranked families; reads tolerate unknown future policy values while writes stay limited to CLI-supported versions.Registers a hidden
entire checkpoint policysubcommand: no flags syncs and prints effectivecheckpoint_version,checkpoint_min_version, andsource; flags set versions, update locally, then push. No hook or command enforcement in this PR—that is deferred to a follow-up.Reviewed by Cursor Bugbot for commit f3c10b3. Configure here.