document checkpoint policy enforcement · Entire

document checkpoint policy enforcement

6f06a73→main·

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

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 <agent> 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