docs: remove checkpoints v1.1 architecture notes

b0f941d→main

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
{
```