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
Changes git remote fetch/push and local ref semantics for a shared policy ref; mistaken policy updates could affect future format rollout, but the command is hidden and enforcement is not wired in this PR.

Overview
Introduces a checkpoint policy model (checkpoint_version / checkpoint_min_version) stored as policy.json on git ref refs/entire/policies/checkpoint, with sync, update, and push against the same checkpoint remote used for checkpoint storage.

Adds a hidden entire checkpoint policy command: with no flags it syncs and prints effective policy and source; with --checkpoint-version / --checkpoint-min-version it validates (CLI-supported write/read sets), blocks downgrades unless --force, writes a new local policy commit, then pushes only that policy ref. Format helpers gain CanWrite, Compare, and family ordering for downgrade checks; reads tolerate unknown future policy values while updates stay strict.

No runtime enforcement in hooks or other commands yet—that is deferred to a follow-up PR.

^{Reviewed by Cursor Bugbot for commit 19e7b88. 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

[pfleidi]

Bugbot run

[cursor]

✅ 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 19e7b88. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.