test+docs: pin the settings-driven git-refs default end to end

7de308d→main· peyton-alt·10h ago·3 files·+56 added/-2 removed

Review findings on PR #1789: - TestEnableDefault_GitRefsRoundTrip exercises the shipped default without the env override every other backend-aware suite uses: enable writes the git-refs primary into settings, and that block alone drives condensation onto per-checkpoint refs. - Architecture docs no longer call git-branch 'the default' — it is the config-less fallback; new setups get an explicit git-refs primary.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

Changes

3

• cmd/entire/cli/integration_test

• Aenable_backend_default_test.go+54

• docs/architecture

• Mref-checkpoint-backend.md+1/-1

  • Msessions-and-checkpoints.md+1/-1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

//go:build integration

package integration

import (
    "strings"
    "testing"

"github.com/entireio/cli/cmd/entire/cli/testutil"
)

// TestEnableDefault_GitRefsRoundTrip pins the shipped first-run default end
// to end WITHOUT the ENTIRE_CHECKPOINTS_PRIMARY override every other
// backend-aware suite uses: a fresh `enable` writes the git-refs primary
// into settings.json, and that settings block alone drives checkpoint
// storage — condensation lands on per-checkpoint refs, not the v1 branch.
// Without this, a regression in the enable→settings→git-refs chain would
// pass the entire env-driven integration and e2e suites.
func TestEnableDefault_GitRefsRoundTrip(t *testing.T) {
    t.Parallel()

env := NewTestEnv(t)
    testutil.InitRepo(t, env.RepoDir)
    env.WriteFile("README.md", "# fresh repo\n")
gitOutput(t, env.RepoDir, "add", "README.md")
gitOutput(t, env.RepoDir, "commit", "-m", "initial commit")

env.RunCLI("enable", "--agent", "claude-code", "--telemetry=false")

settings := env.ReadFile(".entire/settings.json")
    if !strings.Contains(settings, `"git-refs"`) {
        t.Fatalf("first-run enable should write the git-refs primary into settings.json, got:\n%s", settings)
    }

initialHead := gitOutput(t, env.RepoDir, "rev-parse", "HEAD")
sess := env.NewSession()
prompt := "Create a file"
if err := env.SimulateUserPromptSubmitWithPromptAndTranscriptPath(sess.ID, prompt, sess.TranscriptPath); err != nil {
    t.Fatalf("user-prompt-submit failed: %v", err)
}
const content = "package main\n\nfunc main() {}\n"
env.WriteFile("main.go", content)
sess.CreateTranscript(prompt, []FileChange{{Path: "main.go", Content: content}})
if err := env.SimulateStop(sess.ID, sess.TranscriptPath); err != nil {
    t.Fatalf("stop hook failed: %v", err)
}
_ = initialHead
env.GitCommitWithShadowHooks("Add main", "main.go")

refs := gitOutput(t, env.RepoDir, "for-each-ref", "refs/entire/checkpoints")
if refs == "" {
    t.Fatal("expected the condensed checkpoint as a per-checkpoint ref under refs/entire/checkpoints (settings-driven git-refs)")
}
}

Checkpoint version and policy

Mdocs/architecture/ref-checkpoint-backend.md+1/-1

| Persistent (git-branch) | entire/checkpoints/v1 branch, sharded <id[:2]>/<id[2:]>/ | Metadata + commit reference | | Persistent (git-refs) | refs/entire/checkpoints/<shard>/<id>, one ref per checkpoint | Metadata + commit reference |

The persistent store is pluggable: git-branch (the default) stores every committed checkpoint as a subtree of a single entire/checkpoints/v1 branch, while git-refs stores one ref per checkpoint. Both are git-backed and share the same checkpoint tree layout; they differ only in where that tree is committed. This document describes the git-branch layout; for the ref-based backend — its ref naming, sharding, push/fetch model, read routing, and configuration — see Ref-Based Checkpoint Backend. The persistent store is pluggable: git-branch stores every committed checkpoint as a subtree of a single entire/checkpoints/v1 branch, while git-refs stores one ref per checkpoint. New setups get git-refs written into their settings by entire enable; a repo with no checkpoints config still resolves to git-branch (the config-less fallback), so pre-existing repos keep their behavior. Both are git-backed and share the same checkpoint tree layout; they differ only in where that tree is committed. This document describes the git-branch layout; for the ref-based backend — its ref naming, sharding, push/fetch model, read routing, and configuration — see Ref-Based Checkpoint Backend.

Session State

Mdocs/architecture/sessions-and-checkpoints.md+1/-1