Add repo checkpoint policy

[pfleidi]

Why

Repositories need a repo-wide checkpoint policy so older CLIs can warn users before writing incompatible checkpoint data, and user-driven commands can fail clearly when they cannot decode a checkpoint format.

Usage Examples

The policy command is hidden while the surface is still in active development, but it is callable directly.

Inspect the current effective policy:

entire policy checkpoint

Example output:

checkpoint_version: branch-v1
checkpoint_min_version: branch-v1
source: remote

Set the checkpoint version the repo should write:

entire policy checkpoint --checkpoint-version branch-v1

Set the minimum checkpoint version required by the repo:

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

Set both values in one update:

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

Allow an explicit downgrade:

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

On updates, the command refreshes the latest policy from the configured checkpoint remote, validates the requested change against the current CLI capabilities, updates the local refs/entire/policies/checkpoint ref, and pushes only that policy ref.

What Changed

This adds a checkpoint policy stored in refs/entire/policies/checkpoint, backed by a versionable commit containing policy.json. Policy commits follow the existing checkpoint commit-signing settings when signing is configured. If no signing is configured, policy commits are not signed.

The PR adds hidden entire policy checkpoint commands for inspection and updates, applies compatibility warnings to user-driven commands, and teaches hooks and pre-push to respect the policy without breaking ordinary git workflows.

Technical Tradeoffs

• Store policy in a Git ref instead of .entire/settings.json: this makes the policy repo-wide, versionable, and compatible with commit signing, but it adds Git ref sync and divergence handling.
• Reuse the existing checkpoint remote resolver: policy commands and hooks now resolve the same repo-wide checkpoint remote instead of adding a separate remote-selection path. This assumes policy belongs with checkpoint storage, not with the current branch or current push remote.
• Keep offline hooks non-networked: post-commit and agent lifecycle hooks read only the local policy so normal Git usage works offline. The tradeoff is that those hooks can act on a stale local policy until an explicit policy command or pre-push refreshes it.
• Make hooks warn or skip instead of fail: hook-triggered writes may come from agents or editor integrations, so incompatible write policy skips checkpoint persistence and warns only in interactive terminals. User-driven read commands fail when they cannot decode checkpoint data.
• Avoid a SemVer dependency for now: checkpoint formats are parsed as family plus numeric major version. This keeps the implementation small while current support is limited to branch-v1.
• Defer policy signature verification: this PR writes policy commits through the existing checkpoint signing path when signing is configured, but readers do not verify signatures before accepting a policy ref.
• Hide the new command group during development: the command is usable for rollout and testing, but it is not advertised in help while the CLI surface is still settling.

Decisions And Assumptions

• Use policy terminology instead of config terminology because this state is stored in Git, not local JSON settings.
• Use entire policy checkpoint rather than entire configure so users do not expect .entire/settings.json to change.
• Use the singular ref refs/entire/policies/checkpoint, aligned with the singular policy checkpoint command.
• Keep version numbers out of the ref name so future policy format changes are represented by committed content rather than ref namespace churn.
• Treat missing checkpoint versions as branch-v1; that behavior comes from the predecessor checkpoint-version PR.
• Only allow configuring checkpoint versions supported by the current CLI. Downgrades are rejected unless --force is provided.
• Use pre-push as the regular online policy refresh point because Git workflows should remain functional offline and pre-push already requires remote access.
• Fetch the remote policy before applying updates so local changes are validated against the latest remote state.
• Push only the policy ref after policy updates, not the broader checkpoint refs.
• Consider branch-v1 readable and writable today. Known future families such as refs-v1 are parsed but treated as unsupported until this CLI learns to read or write them.

Reviewer Notes

The policy flow intentionally follows the configured checkpoint remote. For repos with a separate checkpoint storage remote, this may differ from the ordinary Git origin, and that should be called out during rollout.

Policy commit signature verification is intentionally out of scope for this change.

---

Note

Medium Risk
Touches checkpoint write/read paths across hooks, pre-push, attach, resume, and explain—incorrect policy sync or enforcement could skip metadata pushes or block legitimate workflows, but behavior is largely fail-closed with tests and offline hook fallbacks.

Overview
Introduces repo-wide checkpoint policy stored at refs/entire/policies/checkpoint (policy.json with checkpoint_version / checkpoint_min_version), plus a new checkpointpolicy package for format parsing (branch-v1 vs future families like refs-v1), validation, local Git storage, and remote sync/push against the configured checkpoint remote.

Adds hidden entire policy checkpoint to inspect or update policy (with downgrade protection unless --force), pushing only the policy ref on updates. User-driven writes (attach, explain summary generation) fail when local policy requires a checkpoint format this CLI cannot write; reads (explain, export, resume, rewind) fail on unsupported per-checkpoint checkpoint_version. Hooks skip checkpoint writes and warn in interactive TTY when write policy is unsupported; pre-push syncs remote policy and can skip checkpoint pushes on unsupported write or diverged local/remote policy. Successful CLI runs (except hooks/analytics) can print an upgrade warning when policy needs a newer Entire.

Also refactors checkpoint-remote HTTPS token handling into checkpointTokenTransport and adds ConfiguredURL for policy remote resolution; documents checkpoint policy in architecture docs.

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

[Copilot]

Pull request overview

This PR introduces a repo-wide checkpoint policy stored in Git (refs/entire/policies/checkpoint) so the CLI and hooks can warn/skip incompatible checkpoint writes and fail clearly on unsupported checkpoint reads, improving cross-version compatibility for checkpoint data.

Changes:

• Add a new checkpointpolicy package that reads/writes a versioned policy.json commit and can sync/push it against the configured checkpoint remote.
• Add entire policy checkpoint for inspecting/updating the repo policy, plus a global post-command warning when the policy requires a newer CLI.
• Enforce checkpoint format compatibility checks in user-driven commands (explain/resume) and in manual-commit strategy flows (pre-push, condensation, log restore).

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/architecture/sessions-and-checkpoints.md	Documents the new repo-wide checkpoint policy ref, schema, and hook/command behaviors.
cmd/entire/main.go	Adds a post-command policy upgrade warning gate based on the executed command.
cmd/entire/cli/versioncheck/versioncheck.go	Exposes an exported helper to produce the update command for the current binary.
cmd/entire/cli/versioncheck/versioncheck_test.go	Adds coverage for the exported update-command wrapper.
cmd/entire/cli/strategy/manual_commit_rewind.go	Rejects restoring logs for checkpoints with unsupported checkpoint versions.
cmd/entire/cli/strategy/manual_commit_push.go	Syncs policy during pre-push and blocks checkpoint pushing when writes are unsupported.
cmd/entire/cli/strategy/manual_commit_hooks.go	Skips committed checkpoint finalization when policy disallows writes.
cmd/entire/cli/strategy/manual_commit_condensation.go	Skips condensation (committed checkpoint write) when policy disallows it.
cmd/entire/cli/strategy/checkpoint_policy.go	Implements strategy-level helpers for policy read/sync + warn/log behavior.
cmd/entire/cli/strategy/checkpoint_policy_test.go	Verifies pre-push behavior when policy requires a newer checkpoint writer.
cmd/entire/cli/root.go	Registers the new policy noun group.
cmd/entire/cli/resume.go	Enforces checkpoint-version readability when resuming sessions and when reading checkpoint info.
cmd/entire/cli/policy_group.go	Adds entire policy command group with git-repo prerequisite check.
cmd/entire/cli/policy_checkpoint.go	Implements entire policy checkpoint sync/update/push and output.
cmd/entire/cli/policy_checkpoint_test.go	Adds tests for defaults, rejects unsupported versions/downgrades, and pushes only the policy ref.
cmd/entire/cli/explain.go	Enforces checkpoint-version readability before decoding checkpoint content.
cmd/entire/cli/checkpointpolicy/policy.go	Defines policy schema, validation, and read-compat enforcement helpers.
cmd/entire/cli/checkpointpolicy/policy_test.go	Tests default policy and validation error cases.
cmd/entire/cli/checkpointpolicy/format.go	Adds parsing/comparison and read/write support matrices for checkpoint formats.
cmd/entire/cli/checkpointpolicy/format_test.go	Tests format parsing and support matrix behavior.
cmd/entire/cli/checkpointpolicy/store.go	Implements local policy ref read/write using a signed/versioned commit with policy.json.
cmd/entire/cli/checkpointpolicy/store_test.go	Tests local policy read/write behavior and malformed/unsupported policy handling.
cmd/entire/cli/checkpointpolicy/remote.go	Implements remote check/fetch/sync and push of the policy ref, including diverged-local detection.
cmd/entire/cli/checkpointpolicy/remote_test.go	Tests sync/push behaviors against a bare remote, including divergence and fast-forward failures.
cmd/entire/cli/checkpointpolicy/update.go	Implements update flow using remote as baseline and downgrade rejection unless --force.
cmd/entire/cli/checkpointpolicy/update_test.go	Tests downgrade rejection and --force override behavior.
cmd/entire/cli/checkpointpolicy/warning_test.go	Tests upgrade warning text and per-checkpoint read-compat enforcement.
cmd/entire/cli/checkpoint/open.go	Adjusts the temporary store accessor (but currently drops an ireturn suppression).
cmd/entire/cli/checkpoint_policy_warning.go	Adds logic to decide whether to show policy warnings and prints upgrade guidance when needed.
cmd/entire/cli/checkpoint_policy_warning_test.go	Adds tests for warning emission and command filtering logic.
cmd/entire/cli/checkpoint_policy_read_test.go	Adds a regression test ensuring unsupported checkpoint versions are rejected when reading checkpoint info.

[pfleidi]

Bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

[Copilot]

Pull request overview

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

[pfleidi]

This PR will be split up into three to separate out logical parts. Closing this for now.