Gate checkpoint writes on policy support by pfleidi · Pull Request #1541 · entireio/cli

pfleidi · 2026-06-27T00:11:15Z

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

Why

Checkpoint policies let repo admins steer checkpoint format rollout, but unsupported policies should only block work that would create checkpoint data the current CLI cannot satisfy. Git hooks and ordinary commands should not make users lose workflow progress because a policy was bumped by another client.

What changed

checkpoint_version now selects the checkpoint metadata format used for new writes. If the field is unset, Entire uses the CLI default. entire checkpoint policy --checkpoint-version "" removes the field so the repo inherits that default again.

checkpoint_min_version is an upgrade nudge and checkpoint-data write guard. Clients that cannot read that version warn users to upgrade, and commands that create checkpoint data fail until the CLI is upgraded. It can also be unset with entire checkpoint policy --checkpoint-min-version "".

The policy command validates requested values when setting policy, so this CLI will not write policy versions it does not support. Downgrades still require --force.

Behavior by path

Checkpoint-data writer commands now fail when the current CLI cannot satisfy the configured policy or cannot read the policy ref. This covers entire session attach, checkpoint explain flows that generate checkpoint data, and checkpoint import.

Agent session startup warns and does not claim or capture the session when the policy requires a newer CLI or cannot be read. Later agent hooks fail loudly with a message that no Entire checkpoints will be created until the CLI is upgraded or the policy can be read.

Git hooks return success but skip Entire checkpoint work when the policy is unsupported or unreadable. This keeps commits, rewrites, and pushes from being blocked by checkpoint policy problems.

Pre-push policy sync still warns on sync, divergence, and read issues. The repo opened for policy sync is reused for policy gating and OPF rewriting.

Docs and tests

Updated CLI help text and docs/architecture/sessions-and-checkpoints.md for checkpoint policy semantics, empty-string unset behavior, default display, and hook behavior.

Added coverage for unsupported and unreadable policies across attach/import/explain, agent hooks, Git hooks, condensation/finalization, policy update/unset, and persistent checkpoint metadata.

Note

Medium Risk
Changes centralize checkpoint-data gating across attach, import, explain, condensation, and agent/git hooks; incorrect policy reads or skip-vs-fail choices could drop checkpoints or allow writes under unsupported formats.

Overview
Checkpoint policy now drives which metadata format new writes use and when the CLI may create checkpoint data, without blocking normal Git or agent sessions when the policy is ahead of this binary.

Policy model and CLI: Stored policy keeps unset fields as empty JSON (defaults apply via Normalize). entire checkpoint policy uses flag Changed so --checkpoint-version "" / --checkpoint-min-version "" can unset fields; output labels inherited defaults and flags unsupported configured versions. CanSatisfyPolicy combines writable checkpoint_version and readable checkpoint_min_version; richer UnsupportedPolicyMessage replaces the old upgrade blurb.

Writers: WriteOptions / attach / condensation pass CheckpointVersion from policy (persistent store honors explicit version). Shared helpers checkpointVersionForNewCheckpoint and ensureCheckpointPolicyAllowsCheckpointData fail attach, import, and explain --generate when policy is unreadable or unsatisfiable.

Hooks: Session-start agent hooks warn and skip claiming the session; turn-end / subagent-end / PostTodo fail with checkpoint-capture-disabled messaging. Git hooks always succeed but skip Entire work (including unreadable policy). Pre-push still syncs policy, then skips checkpoint push when unsatisfied (diverged policy no longer blocks push).

Strategy: Condensation/finalization errors or skips on bad policy instead of the old committed-write block; pre-push behavior aligned with warn-and-skip.

Docs and tests updated for unset semantics, command paths, and hook behavior.

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

Resolve the effective checkpoint_version from repo policy while falling back to the CLI default when the configured value is unsupported. Thread the selected version through checkpoint writes so storage records the caller-selected format for new summaries. Entire-Checkpoint: 79be90295d5a

Treat unsupported checkpoint write policies as upgrade nudges instead of blocking attach, summary, hook, and pre-push writes. Use the configured checkpoint version when this CLI can write it, and fall back to the default version when it cannot. Entire-Checkpoint: b60f4de0a520

Explain that checkpoint_version controls new writes but falls back to the CLI default when unsupported. Describe min_checkpoint_version as an upgrade nudge and keep command help aligned with the architecture docs. Entire-Checkpoint: 7a1017867a5d

Drop the repository argument left behind after policy enforcement moved out of summary generation. This keeps the summary helper signature aligned with the data it actually uses. Entire-Checkpoint: 16e73f62b845

Add explicit unset flags for checkpoint_version and checkpoint_min_version. Persist unset fields as omitted JSON and derive effective defaults with policy normalization where needed. Entire-Checkpoint: 303f7958de64

Treat provided empty checkpoint policy flag values as field removal. This keeps the command surface smaller while preserving the ability to distinguish omitted flags from explicit empty values. Entire-Checkpoint: 6d800e6c1307

Copilot

Pull request overview

This PR changes repo checkpoint policy handling from “enforced” to “advisory” so unsupported or newer policy settings don’t block checkpoint writes, hooks, condensation, or pre-push behavior. It preserves fail-open behavior by warning and falling back to the CLI’s default writable checkpoint format.

Changes:

Treat checkpoint_min_version as advisory-only (warn/upgrade nudge; no blocking).
When a configured checkpoint_version is unsupported by this CLI, warn and fall back to the CLI default version for writes.
Allow unsetting policy fields by explicitly passing empty flag values, storing omitted JSON fields rather than normalized defaults.

Reviewed changes

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

Show a summary per file

File	Description
docs/architecture/sessions-and-checkpoints.md	Updates policy semantics documentation (advisory min version; fallback behavior; unsetting).
cmd/entire/cli/strategy/manual_commit_hooks.go	Hooks now warn (when possible) but no longer block/skip turn-finalization due to policy.
cmd/entire/cli/strategy/manual_commit_condensation.go	Condensation selects an effective checkpoint version (policy-supported or default) and warns when policy indicates upgrade need.
cmd/entire/cli/strategy/checkpoint_policy.go	Refactors policy reading/sync to fail-open and centralizes upgrade warning behavior.
cmd/entire/cli/strategy/checkpoint_policy_test.go	Updates strategy tests to reflect advisory/fallback behavior and always-allow pre-push.
cmd/entire/cli/explain.go	Summary generation no longer enforces blocking policy checks.
cmd/entire/cli/explain_test.go	Adjusts summary-generation tests for fail-open policy behavior.
cmd/entire/cli/checkpointpolicy/update.go	Adds “flag was set” booleans to support explicit unsetting and avoids normalization-on-write in returned state.
cmd/entire/cli/checkpointpolicy/update_test.go	Adds/updates tests for unsetting behavior and changed update semantics.
cmd/entire/cli/checkpointpolicy/store.go	Stops auto-defaulting/normalizing on read/write; preserves omitted fields as unset.
cmd/entire/cli/checkpointpolicy/store_test.go	Tests round-tripping empty policy `{}` and default normalization behavior.
cmd/entire/cli/checkpointpolicy/remote_test.go	Updates defaults behavior assertions to match “empty policy means defaults”.
cmd/entire/cli/checkpointpolicy/policy.go	Adds `omitempty` tags, `DefaultCheckpointVersion`, and `CheckpointVersion(policy)` helper for safe fallback.
cmd/entire/cli/checkpointpolicy/policy_test.go	Adds unit coverage for `CheckpointVersion(policy)` fallback behavior.
cmd/entire/cli/checkpoint/persistent.go	Allows callers to explicitly set `checkpoint_version` in root summaries via `WriteOptions.CheckpointVersion`.
cmd/entire/cli/checkpoint/persistent_write_test.go	Adds test verifying explicit `CheckpointVersion` is persisted.
cmd/entire/cli/checkpoint_policy.go	Improves policy command help text and supports explicit unsetting via flag-changed detection; prints defaults with `(default)`.
cmd/entire/cli/checkpoint_policy_write.go	Replaces hard-blocking policy enforcement with “effective committed checkpoint version” resolution for writers.
cmd/entire/cli/checkpoint_policy_test.go	Updates command output expectations and adds help/unset coverage.
cmd/entire/cli/attach.go	Attach writes now include an explicit effective `CheckpointVersion` (policy-supported or default).
cmd/entire/cli/attach_test.go	Updates attach behavior test to expect fallback/default write instead of rejection.
api/checkpoint/metadata.go	Extends checkpoint write contract with `CheckpointVersion` for new root summaries.

pfleidi · 2026-06-27T00:18:13Z

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 d995bcb. Configure here.}

Policy sync is advisory now, so keep the helper focused on sync and warning side effects instead of returning a push gate. Entire-Checkpoint: b36a51f8fc56

Clarify that empty-value policy unsets inherit the CLI default while still using the normal downgrade guard, so --force may be required. Entire-Checkpoint: 44797dac9f78

pfleidi · 2026-06-29T17:37:15Z

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 fa54b81. Configure here.}

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Show when unsupported configured checkpoint versions write the default and log policy read failures before falling back. Entire-Checkpoint: 27c77d50dda9

Add one predicate for unsupported checkpoint policy and centralize the user-facing upgrade details. Remove the exported upgrade-warning helper now that callers use the diagnostic message helper directly. Entire-Checkpoint: 90243197507f

Reject explicit checkpoint-data writes when the local checkpoint policy requires unsupported checkpoint versions. Entire-Checkpoint: 89792fc1526a

Make agent hooks surface unsupported checkpoint policy loudly while Git hooks skip checkpoint work without blocking Git. Entire-Checkpoint: fb1150b8797e

Update help and architecture docs for unsupported checkpoint policy behavior across commands and hooks. Entire-Checkpoint: 1ff5c86c523f

…li into checkpoint-policy-fixes # Conflicts: # cmd/entire/cli/explain.go

Treat malformed local checkpoint policy refs as read errors for checkpoint-data writers and strategy checkpoint work. Agent hooks surface read-specific disabled-checkpoint messages, while Git hooks skip checkpoint work without blocking Git. Entire-Checkpoint: 8dfabaa3d786

Use normalized policy values directly at checkpoint write call sites. This keeps unsupported policy decisions in CanSatisfyPolicy instead of hiding them behind a version accessor. Entire-Checkpoint: 76a5489de55e

Keep shared CLI checkpoint policy fixtures together instead of storing one in attach tests. Entire-Checkpoint: 98e7269509d0

Open the repository once during pre-push and pass it through checkpoint policy sync and gating. Document why policy failures skip checkpoint work instead of failing Git or agent session startup hooks. Entire-Checkpoint: d632fcef7305

Delegate the empty/default case to formatCheckpointPolicyValue so the version formatter expresses only its one delta, the unsupported case. Entire-Checkpoint: f54fb5a360a3

pfleidi · 2026-06-30T00:17:17Z

Bugbot run

Copilot

Pull request overview

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

Treat agent and Git hook repository open failures as unreadable checkpoint policy. Agent hook policy lookup is separated from policy evaluation so callers decide how session-start and later hooks respond. Entire-Checkpoint: 43c4391add10

…eckpoint-policy-fixes

Entire-Checkpoint: 6f768b8c2faf

Keep SessionStart warning-only and let non-writing lifecycle hooks dispatch when checkpoint policy cannot be satisfied. This preserves TurnStart session initialization and context injection while still blocking hooks that directly write checkpoint data. Entire-Checkpoint: 07130ba2ded6

pfleidi · 2026-06-30T18:14:39Z

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 623aa66. Configure here.}

pfleidi added 6 commits June 26, 2026 15:29

document checkpoint policy fallback

5173da4

Explain that checkpoint_version controls new writes but falls back to the CLI default when unsupported. Describe min_checkpoint_version as an upgrade nudge and keep command help aligned with the architecture docs. Entire-Checkpoint: 7a1017867a5d

remove stale checkpoint summary repo parameter

b0eed5c

Drop the repository argument left behind after policy enforcement moved out of summary generation. This keeps the summary helper signature aligned with the data it actually uses. Entire-Checkpoint: 16e73f62b845

support unsetting checkpoint policy fields

f4bced8

Add explicit unset flags for checkpoint_version and checkpoint_min_version. Persist unset fields as omitted JSON and derive effective defaults with policy normalization where needed. Entire-Checkpoint: 303f7958de64

use empty policy flag values to unset

d995bcb

Treat provided empty checkpoint policy flag values as field removal. This keeps the command surface smaller while preserving the ability to distinguish omitted flags from explicit empty values. Entire-Checkpoint: 6d800e6c1307

Copilot AI review requested due to automatic review settings June 27, 2026 00:11

Copilot started reviewing on behalf of pfleidi June 27, 2026 00:11 View session

Copilot AI reviewed Jun 27, 2026

View reviewed changes

Comment thread cmd/entire/cli/checkpointpolicy/update.go

cursor Bot reviewed Jun 27, 2026

View reviewed changes

Merge branch 'main' into checkpoint-policy-fixes

8fb1567

pfleidi marked this pull request as ready for review June 29, 2026 17:17

pfleidi requested a review from a team as a code owner June 29, 2026 17:17

pfleidi added 2 commits June 29, 2026 10:21

simplify checkpoint policy pre-push sync

e5feacd

Policy sync is advisory now, so keep the helper focused on sync and warning side effects instead of returning a push gate. Entire-Checkpoint: b36a51f8fc56

document checkpoint policy unset downgrades

fa54b81

Clarify that empty-value policy unsets inherit the CLI default while still using the normal downgrade guard, so --force may be required. Entire-Checkpoint: 44797dac9f78

pfleidi requested a review from Copilot June 29, 2026 17:37

Copilot started reviewing on behalf of pfleidi June 29, 2026 17:37 View session

cursor Bot reviewed Jun 29, 2026

View reviewed changes

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread cmd/entire/cli/checkpoint_policy.go

Comment thread cmd/entire/cli/checkpoint_policy_write.go Outdated

pfleidi added 9 commits June 29, 2026 11:09

surface checkpoint policy fallbacks

c3f89a9

Show when unsupported configured checkpoint versions write the default and log policy read failures before falling back. Entire-Checkpoint: 27c77d50dda9

clarify checkpoint policy satisfaction

65d3736

Add one predicate for unsupported checkpoint policy and centralize the user-facing upgrade details. Remove the exported upgrade-warning helper now that callers use the diagnostic message helper directly. Entire-Checkpoint: 90243197507f

block checkpoint data writers on policy

c553b61

Reject explicit checkpoint-data writes when the local checkpoint policy requires unsupported checkpoint versions. Entire-Checkpoint: 89792fc1526a

gate hooks on checkpoint policy

a117171

Make agent hooks surface unsupported checkpoint policy loudly while Git hooks skip checkpoint work without blocking Git. Entire-Checkpoint: fb1150b8797e

document checkpoint policy enforcement

6f06a73

Update help and architecture docs for unsupported checkpoint policy behavior across commands and hooks. Entire-Checkpoint: 1ff5c86c523f

Merge branch 'main' of entire://aws-us-east-2.entire.io/gh/entireio/c…

93b03f9

…li into checkpoint-policy-fixes # Conflicts: # cmd/entire/cli/explain.go

remove checkpoint version fallback helper

9994d75

Use normalized policy values directly at checkpoint write call sites. This keeps unsupported policy decisions in CanSatisfyPolicy instead of hiding them behind a version accessor. Entire-Checkpoint: 76a5489de55e

move checkpoint policy test helpers

39d9209

Keep shared CLI checkpoint policy fixtures together instead of storing one in attach tests. Entire-Checkpoint: 98e7269509d0

reuse pre-push repo for policy checks

450426a

Open the repository once during pre-push and pass it through checkpoint policy sync and gating. Document why policy failures skip checkpoint work instead of failing Git or agent session startup hooks. Entire-Checkpoint: d632fcef7305

computermode previously approved these changes Jun 30, 2026

View reviewed changes

pfleidi changed the title ~~Make checkpoint policies advisory~~ Gate checkpoint writes on policy support Jun 30, 2026

dedupe checkpoint version policy formatting

7ed08ed

Delegate the empty/default case to formatCheckpointPolicyValue so the version formatter expresses only its one delta, the unsupported case. Entire-Checkpoint: f54fb5a360a3

pfleidi dismissed computermode’s stale review via 7ed08ed June 30, 2026 00:17

Merge branch 'main' into checkpoint-policy-fixes

88eb877

pfleidi requested a review from Copilot June 30, 2026 00:17

Copilot started reviewing on behalf of pfleidi June 30, 2026 00:17 View session

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread cmd/entire/cli/hook_registry.go

Comment thread cmd/entire/cli/hooks_git_cmd.go

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread cmd/entire/cli/strategy/checkpoint_policy.go

Comment thread cmd/entire/cli/hooks_git_cmd.go

Comment thread cmd/entire/cli/hook_registry.go

pfleidi added 5 commits June 29, 2026 17:40

fix hook policy open failures

8127cf5

Treat agent and Git hook repository open failures as unreadable checkpoint policy. Agent hook policy lookup is separated from policy evaluation so callers decide how session-start and later hooks respond. Entire-Checkpoint: 43c4391add10

Merge remote-tracking branch 'origin/checkpoint-policy-fixes' into ch…

342c6fd

…eckpoint-policy-fixes

Merge origin/main into checkpoint-policy-fixes

d958fb7

Entire-Checkpoint: 6f768b8c2faf

Merge remote-tracking branch 'origin/main' into checkpoint-policy-fixes

623aa66

cursor Bot reviewed Jun 30, 2026

View reviewed changes

computermode approved these changes Jun 30, 2026

View reviewed changes

pfleidi merged commit cb610b7 into main Jun 30, 2026
10 checks passed

pfleidi deleted the checkpoint-policy-fixes branch June 30, 2026 18:32

pfleidi mentioned this pull request Jun 30, 2026

Add telemetry for policy-blocked checkpoint hooks #1586

Merged

Uh oh!

Conversation

pfleidi commented Jun 27, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

pfleidi commented Jun 27, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pfleidi commented Jun 29, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

pfleidi commented Jun 30, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pfleidi commented Jun 30, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

pfleidi commented Jun 27, 2026 •

edited by cursor Bot

Loading