document checkpoint policy fallback · Entire

document checkpoint policy fallback

5173da4→main· pfleidi·3w ago·3 files·+53 added/-13 removed

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.

Sessions

7a1017867a5dView transcript

Changes

3

18 unmodified lines

func newCheckpointPolicyCmd() *cobra.Command {
    var opts checkpointPolicyOptions
    cmd := &cobra.Command{
        Use:    "policy",
        Short:  "Inspect and update checkpoint policy",
        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.

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.`,
        Hidden: true,
        Args:   cobra.NoArgs,
        RunE: func(cmd *cobra.Command, _ []string) error {

},
    }

cmd.Flags().StringVar(&opts.version, "checkpoint-version", "", "Set the checkpoint version written by this repository")
    cmd.Flags().StringVar(&opts.minVersion, "checkpoint-min-version", "", "Set the minimum checkpoint version required by this repository")
    cmd.Flags().BoolVar(&opts.force, "force", false, "Allow checkpoint policy version downgrades")
    return cmd
}

Mcmd/entire/cli/checkpoint_policy.go+14/-4

26 unmodified lines

func TestCheckpointPolicyCmd_HelpDocumentsAdvisoryBehavior(t *testing.T) {
    t.Parallel()

cmd := newCheckpointGroupCmd()
    var stdout bytes.Buffer
    cmd.SetOut(&stdout)
    cmd.SetArgs([]string{"policy", "--help"})

err := cmd.Execute()
    require.NoError(t, err)

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, "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")
}

func TestCheckpointPolicyCmd_RejectsUnsupportedVersion(t *testing.T) {
    tests := []struct {
        name    string

checkpoint_version is the checkpoint format new writes should use. checkpoint_min_version is the oldest checkpoint format clients must be able to read for this repo. Missing policy fields default to branch-v1. checkpoint_version selects the checkpoint format for new writes. If no policy is configured, or a policy omits checkpoint_version, the CLI writes its default checkpoint version. If another client configures a checkpoint_version this CLI cannot write, the CLI warns and writes the default checkpoint version instead.

Policy follows the configured checkpoint remote. entire checkpoint policy 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. Missing policy fields default to branch-v1.

entire checkpoint policy validates requested policy values against the current CLI, so it rejects setting unsupported checkpoint versions.

Policy follows the configured checkpoint remote. entire checkpoint policy fetches the latest remote policy before validating requested changes, updates 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 writes this CLI does not support, they skip writing checkpoint data and warn only when running in an interactive terminal. 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, fetches updated policy when needed, and evaluates the refreshed policy before pushing entire/checkpoints/v1. If policy refresh fails, the hook warns or logs the failure and lets the normal push continue. 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.

User-driven commands warn when the local policy indicates the CLI should be upgraded. Commands that need to decode checkpoint contents, such as