# document checkpoint policy enforcement `6f06a73`→[main](/content/gh/entireio/cli/commits/main/index.html)· pfleidi·2w ago·5 files·+68 added/-41 removed Update help and architecture docs for unsupported checkpoint policy behavior across commands and hooks. ## Sessions 1ff5c86c523fView transcript [?\ Enforce Checkpoint Policies in CLICodex·GPT-5.5·1 step](/content/gh/entireio/cli/session/019f05ad-eea0-7202-a508-ec34d069a2d2#timeline-1ff5c86c523f/index.html) ## Changes 5 - cmd/entire/cli - Mcheckpoint_policy.go+17/-12 - Mcheckpoint_policy_test.go+8/-7 - Mimport_cmd.go+5/-1 - Mimport_cmd_test.go+16 - docs/architecture - Msessions-and-checkpoints.md+22/-21 ``` 28 unmodified lines 29 30 31 32 33 34 32 33 34 35 36 36 37 38 37 38 39 40 41 42 43 4 unmodified lines 48 49 50 49 50 51 52 53 54 55 57 unmodified lines 113 114 115 114 116 117 116 118 119 118 119 120 121 122 123 124 125 126 127 28 unmodified lines Long: `Inspect and update checkpoint policy. checkpoint_version selects the checkpoint metadata format used for new writes. If no policy is configured, Entire uses the CLI default. If this CLI reads a configured checkpoint_version it cannot write, it warns and writes the default version instead. Set checkpoint_version to "" to inherit the CLI default. If no policy is configured, Entire uses the CLI default. If another client configures a checkpoint_version this CLI cannot write, commands that create checkpoint data fail until the CLI is upgraded. Other commands warn and continue. Set checkpoint_version to "" to inherit the CLI default. checkpoint_min_version is an upgrade nudge. Clients that cannot read that version warn users to upgrade, but policy alone does not block checkpoint writes or app usage. Set checkpoint_min_version to "" to inherit the CLI default. checkpoint_min_version is an upgrade nudge and checkpoint-data write guard. Clients that cannot read that version warn users to upgrade. Commands that create checkpoint data fail until the CLI is upgraded. Other commands warn and continue. Set checkpoint_min_version to "" to inherit the CLI default. Unsetting a field still uses the normal downgrade guard. If inheriting the default would lower the field's effective version, pass --force to allow it. ``` cmd.Flags().StringVar(&opts.version, checkpointVersionFlag, "", `Set the checkpoint version used for new writes. Use "" to unset; --force may be required`) cmd.Flags().StringVar(&opts.minVersion, checkpointMinVersionFlag, "", `Set the checkpoint version used for upgrade warnings. Use "" to unset; --force may be required`) cmd.Flags().StringVar(&opts.version, checkpointVersionFlag, "", `Set checkpoint_version. Use "" to inherit the CLI default; --force may be required`) cmd.Flags().StringVar(&opts.minVersion, checkpointMinVersionFlag, "", `Set checkpoint_min_version. Use "" to inherit the CLI default; --force may be required`) cmd.Flags().BoolVar(&opts.force, "force", false, "Allow checkpoint policy version downgrades") return cmd } return configured } func formatCheckpointVersionPolicyValue(configured, writeVersion string) string { func formatCheckpointVersionPolicyValue(configured, effective string) string { if configured == "" { return writeVersion + " (default)" return effective + " (default)" } if configured != writeVersion { return fmt.Sprintf("%s (unsupported; writing %s)", configured, writeVersion) if checkpointpolicy.UnsupportedWrite(checkpointpolicy.Policy{ CheckpointVersion: configured, CheckpointMinVersion: checkpointpolicy.DefaultCheckpointVersion(), }) { return configured + " (unsupported)" } return configured } ``` Mcmd/entire/cli/checkpoint_policy.go+17/-12 ``` 26 unmodified lines 27 28 29 30 30 31 32 33 6 unmodified lines 40 41 42 43 43 44 45 45 46 47 46 47 48 49 50 18 unmodified lines 69 70 71 72 72 73 74 75 3 unmodified lines 79 80 81 82 82 83 84 85 86 26 unmodified lines require.Contains(t, stdout, "source: defaults") } func TestCheckpointPolicyCmd_HelpDocumentsAdvisoryBehavior(t *testing.T) { func TestCheckpointPolicyCmd_HelpDocumentsEnforcementBehavior(t *testing.T) { t.Parallel() cmd := newCheckpointGroupCmd() 6 unmodified lines help := stdout.String() require.Contains(t, help, "checkpoint_version selects the checkpoint metadata format used for new writes") require.Contains(t, help, "warns and writes the default") require.Contains(t, help, `If another client configures a checkpoint_version this CLI cannot write`) require.Contains(t, help, "commands that create checkpoint data fail until the CLI is upgraded") require.Contains(t, help, "checkpoint_min_version is an upgrade nudge") require.Contains(t, help, "Set the checkpoint version used for new writes") require.Contains(t, help, "Set the checkpoint version used for upgrade warnings") require.Contains(t, help, `Use "" to unset`) require.Contains(t, help, `Set checkpoint_version to "" to inherit the CLI default`) require.Contains(t, help, `Set checkpoint_min_version to "" to inherit the CLI default`) require.Contains(t, help, "Unsetting a field still uses the normal downgrade guard") require.NotContains(t, help, "unset-checkpoint-version") } 18 unmodified lines } func TestCheckpointPolicyCmd_PrintsWriteFallbackForUnsupportedConfiguredVersion(t *testing.T) { func TestCheckpointPolicyCmd_PrintsUnsupportedConfiguredVersion(t *testing.T) { dir, bareDir := setupCheckpointPolicyRepo(t) seedCheckpointPolicyForCommand(t, dir, checkpointpolicy.Policy{ CheckpointVersion: "refs-v1", 3 unmodified lines stdout, err := executeCheckpointPolicyCmd(t) require.NoError(t, err) require.Contains(t, stdout, "checkpoint_version: refs-v1 (unsupported; writing branch-v1)") require.Contains(t, stdout, "checkpoint_version: refs-v1 (unsupported)") require.NotContains(t, stdout, "writing branch-v1") require.Contains(t, stdout, "checkpoint_min_version: branch-v1") } ``` Mcmd/entire/cli/checkpoint_policy_test.go+8/-7 ``` 35 unmodified lines 36 37 38 39 39 40 41 42 43 44 45 46 35 unmodified lines Short: fmt.Sprintf("Import existing %s transcripts as read-only checkpoints", imp.AgentType()), Long: fmt.Sprintf(`Import pre-existing %s transcripts for this repo (the past month) as read-only checkpoints. Imported history is searchable and explainable but is not rewindable.`, imp.AgentType()), not rewindable. Import honors checkpoint policy before scanning transcripts. If the configured checkpoint_version or checkpoint_min_version is unsupported by this CLI, import fails even with --dry-run.`, imp.AgentType()), Args: cobra.NoArgs, RunE: func(c *cobra.Command, _ []string) error { ctx := c.Context() ``` Mcmd/entire/cli/import_cmd.go+5/-1 ``` 1 unmodified line 2 3 4 5 6 7 8 59 unmodified lines 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 1 unmodified line import ( "bytes" "context" "os" "path/filepath" "strings" 59 unmodified lines require.ErrorContains(t, err, "checkpoint policy cannot be satisfied by this Entire CLI") require.NotContains(t, out.String(), "Would import") } func TestImportClaudeCodeHelpDocumentsCheckpointPolicy(t *testing.T) { t.Parallel() cmd := newImportCmd() var out bytes.Buffer cmd.SetOut(&out) cmd.SetErr(&out) cmd.SetArgs([]string{"claude-code", "--help"}) cmd.SetContext(context.Background()) require.NoError(t, cmd.Execute()) require.Contains(t, out.String(), "Import honors checkpoint policy before scanning transcripts.") require.Contains(t, out.String(), "fails even with --dry-run") } ``` Mcmd/entire/cli/import_cmd_test.go+16 ``` 300 unmodified lines 301 302 303 304 305 304 305 306 307 308 309 310 311 312 307 308 309 310 311 312 313 314 315 8 unmodified lines 324 325 326 327 328 329 330 331 332 333 334 335 336 327 328 329 330 331 332 333 334 335 336 337 339 340 341 338 339 340 341 342 343 344 345 300 unmodified lines empty string with `entire checkpoint policy --checkpoint-version ""`, the CLI writes its default checkpoint version. The quotes are required so the shell passes an empty value instead of omitting the flag value. If another client configures a `checkpoint_version` this CLI cannot write, the CLI warns and writes the default checkpoint version instead. configures a `checkpoint_version` this CLI cannot write, explicit checkpoint-data writers fail until the CLI is upgraded. `checkpoint_min_version` is a soft upgrade nudge. Clients that cannot read that version warn users to upgrade, but policy alone does not block checkpoint writes or app usage. If no policy is configured, a policy omits `checkpoint_min_version`, or the field was set to an empty string with `entire checkpoint policy --checkpoint-min-version ""`, the CLI uses its default minimum checkpoint version for warning decisions. `checkpoint_min_version` is an upgrade nudge and checkpoint-data write guard. Clients that cannot read that version warn users to upgrade. Explicit checkpoint-data writers fail until the CLI is upgraded. If no policy is configured, a policy omits `checkpoint_min_version`, or the field was set to an empty string with `entire checkpoint policy --checkpoint-min-version ""`, the CLI uses its default minimum checkpoint version for policy decisions. Unsetting a field is still evaluated against the normal downgrade guard. If the field's current effective version is newer than the default inherited after 8 unmodified lines the local policy ref, and pushes only `refs/entire/policies/checkpoint`. Policy commits use the same signing settings as checkpoint commits. Hooks that run while ordinary git operations must keep working offline: post-commit and agent lifecycle hooks read only the local policy ref. If the local policy requires checkpoint support this CLI does not have, they warn when running in an interactive terminal and otherwise keep writing checkpoint data with the default checkpoint version. The pre-push hook is the regular online sync point: it compares the remote policy ref with the local ref and fetches updated policy when needed. If policy refresh fails, the policy diverges, or the refreshed policy requires checkpoint support this CLI does not have, the hook warns or logs the issue and still lets the normal push and checkpoint push continue. Agent session-start hooks warn that checkpoint capture is disabled for the session and exit successfully. Other agent hooks fail with a checkpoint-disabled message so the agent can see that no Entire checkpoints will be generated until the CLI is upgraded. Git hooks never block Git because of checkpoint policy. When the policy cannot be satisfied, Git hooks log the violation, warn only in an interactive terminal, skip Entire checkpoint work, and exit successfully. Pre-push refreshes policy first, then applies the same skip behavior to checkpoint push work. User-driven commands warn when the local policy indicates the CLI should be upgraded. Commands that need to decode checkpoint contents, such as `entire checkpoint explain` and `entire session resume`, fail when the target checkpoint uses an unsupported `checkpoint_version`. upgraded. Explicit checkpoint-data writers such as `entire session attach`, `entire checkpoint explain --generate`, and `entire import ` fail when the local policy cannot be satisfied. Commands that need to decode checkpoint contents, such as `entire checkpoint explain` and `entire session resume`, fail when the target checkpoint uses an unsupported `checkpoint_version`. ### Checkpoint ID Linking