Add hidden checkpoint policy command

[pfleidi]

https://entire.io/gh/entireio/cli/trails/654

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 hidden entire checkpoint policy command to inspect or update the policy.

Usage examples

Inspect the effective policy:

entire checkpoint policy

Set the active checkpoint format written by the repo:

entire checkpoint policy --checkpoint-version branch-v1

Set the minimum checkpoint format required by the repo:

entire checkpoint policy --checkpoint-min-version branch-v1

Allow an intentional downgrade:

entire checkpoint policy --checkpoint-version branch-v1 --checkpoint-min-version branch-v1 --force

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 the checkpoint policy command 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
New remote push/sync and ref mutation on the checkpoint remote; behavior is isolated to a dedicated ref and hidden command, with enforcement deferred to a follow-up PR.

Overview
Introduces a checkpoint policy layer stored at refs/entire/policies/checkpoint (policy.json), recording which checkpoint format the repo writes and the minimum format it requires. A new checkpointpolicy package handles format parsing/comparison (CanRead/CanWrite, downgrade checks), local git ref read/write via the existing checkpoint commit path, remote sync against the same checkpoint remote as storage, and push of only that policy ref.

Adds a hidden entire checkpoint policy command: with no flags it syncs and prints effective checkpoint_version, checkpoint_min_version, and source; with --checkpoint-version / --checkpoint-min-version it updates (validates CLI-supported versions, blocks downgrades unless --force), then pushes the policy ref. Reads tolerate future/unsupported policy values; updates stay strict. No hook or runtime enforcement in this PR.

^{Reviewed by Cursor Bugbot for commit 6804095. Configure here.}

[Copilot]

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 policy command group with a visible entire policy checkpoint subcommand for inspecting/updating policy state.
• Introduces checkpointpolicy storage + remote sync/update/push helpers for refs/entire/policies/checkpoint (persisted as policy.json in 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.

[pfleidi]

Bugbot run

[pfleidi]

Bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ 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 6804095. Configure here.}