# docs: remove checkpoints v1.1 architecture notes

`b0f941d`→[main](/content/gh/entireio/cli/commits/main/index.html)

Update checkpoint documentation for the v1-only committed metadata path after retiring the custom read mirror.

## Sessions

62eca7314d85View transcript

## Changes

2

- MCLAUDE.md-1
- docs/architecture

- Msessions-and-checkpoints.md-31

```
464 unmodified lines
```

- **Worktree-specific branches** - each git worktree gets its own shadow branch namespace, preventing conflicts
- **Supports multiple concurrent sessions** - checkpoints from different sessions in the same directory interleave on the same shadow branch
- Condenses session logs to permanent `entire/checkpoints/v1` branch on user commits
- When `checkpoints_version` is `1.1`, best-effort mirrors v1 metadata to the `refs/entire/checkpoints/v1.1` read ref after entire-managed v1 writes and fetches; mirror failures are logged, not fatal. The resolver also adds v1.1 to the push set, so `PrePush` pushes it to the configured remote alongside v1 (re-pointing the mirror at the current v1 tip first); v1.1 is a non-branch ref, so it gets no origin-tracking shadow and reads do not bootstrap it from origin (reads target v1.1 while Primary stays v1). The resume bootstrap that promotes local v1 from origin's remote-tracking ref is the deliberate exception — it does not mirror and is skipped entirely in v1.1 mode. Read paths use the configured ref as-is.
- Uses the `post-rewrite` Git hook to keep local session linkage aligned after amend/rebase rewrites
- Builds git trees in-memory using go-git plumbing APIs
- Rewind restores files from shadow branch commit tree (does not use `git reset`)
```

MCLAUDE.md-1

````
const (
    Temporary Type = iota // Full state snapshot, shadow branch
    Committed             // Metadata + commit ref, entire/checkpoints/v1
                          // (or the local v1.1 read mirror when configured)
)
````

| Session State | `.git/entire-sessions/<id>.json` | Active session tracking |
| Temporary | `entire/<commit[:7]>-<worktreeHash[:6]>` branch | Full state (code + metadata) |
| Committed | `entire/checkpoints/v1` branch (sharded) | Metadata + commit reference |
| Committed read mirror | `refs/entire/checkpoints/v1.1` ref | Mirror used by v1.1 reads; pushed alongside v1 when opted in |

### Session State

└── 2/                   # Third session...

#### v1.1 local read mirror

`entire/checkpoints/v1` remains the durable source of truth: committed writes target this branch, and push/fetch operations synchronize this branch with remotes. When `strategy_options.checkpoints_version` is `"1.1"`, committed reads resolve against `refs/entire/checkpoints/v1.1` instead.

The v1.1 ref lives outside `refs/heads/` and does not appear in normal branch listings. It is pushed to the configured remote alongside `entire/checkpoints/v1` — the resolver adds it to the push set and `PrePush` pushes every ref there. Because it is not a branch it gets no `refs/remotes/origin/...` tracking ref, and reads still resolve against the local ref rather than bootstrapping it from origin (reads target v1.1 while the primary write/fetch ref stays `entire/checkpoints/v1`). Entire-managed v1 write and fetch paths advance the mirror best-effort after they advance `entire/checkpoints/v1`; mirror failures are logged but never fail the primary operation. `PrePush` re-points the mirror at the v1 tip before pushing so the published ref reflects the current primary. The resume bootstrap that promotes local v1 from origin's remote-tracking ref is the deliberate exception — it does not mirror and is skipped entirely in v1.1 mode.

Read paths do not create, repair, or advance the mirror before use; they read the configured committed-read ref as-is. The repair tool is `entire doctor`: it diagnoses a missing, stale (behind v1), or diverged mirror via `strategy.DiagnoseCommittedMetadataMirror` and — with confirmation, or automatically under `--force` — points the mirror back at the v1 tip. `entire doctor bundle` captures the entire-related refs and the mirror diagnosis in `entire-refs.txt.

**Root-level metadata.json (`CheckpointSummary`):**
```json
{
```