From 7b695b2a8faa41aa243cb08f6e3c9ab19b8fe1f4 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Thu, 2 Apr 2026 17:05:32 -0700
Subject: [PATCH 01/17] docs: add command-first checkpoints v2 manual test
 guide

Entire-Checkpoint: f9f4c9654206
---
 .../guides/checkpoints-v2-manual-test-plan.md | 640 ++++++++++++++++++
 1 file changed, 640 insertions(+)
 create mode 100644 docs/guides/checkpoints-v2-manual-test-plan.md

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
new file mode 100644
index 0000000000..5d6c3d64e6
--- /dev/null
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -0,0 +1,640 @@
+# Checkpoints v2 Manual Test Plan (Command-First)
+
+## Purpose
+
+This is the command-first manual QA plan for the checkpoints v2 migration. It is intended to be used throughout rollout without needing rewrites as additional command support lands.
+
+Goals:
+- Validate v2 split-ref read/write behavior.
+- Validate local-missing/remote-present fetch behavior.
+- Validate rotation, cleanup, and migration lifecycle behavior.
+- Provide copy-paste test steps and evidence collection.
+
+## v2 Invariants
+
+- Permanent metadata + compact transcripts: `refs/entire/checkpoints/v2/main`
+- Raw resumable logs: `refs/entire/checkpoints/v2/full/current`
+- Archived raw generations: `refs/entire/checkpoints/v2/full/<generation>`
+- v1 fallback remains available until v1 removal
+
+## Global Test Setup
+
+### Test topology
+
+Use three clones of one test repository:
+- `repo-a`: primary writer and command runner
+- `repo-b`: secondary writer for concurrency and remote edge cases
+- `repo-fresh`: clean clone for fetch-on-demand tests
+
+Optional: a dedicated checkpoint remote repository for `checkpoint_remote` scenarios.
+
+### Settings
+
+Set strategy options in `.entire/settings.json`:
+
+```json
+{
+  "strategy_options": {
+    "checkpoints_v2": true,
+    "push_v2_refs": true,
+    "generation_retention_days": 14
+  }
+}
+```
+
+### Baseline checks (run before each command section)
+
+```bash
+# Verify v2 metadata ref exists locally (or not, for fallback scenarios)
+git show-ref --verify -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Verify v2 raw current-generation ref exists locally
+git show-ref --verify -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# List all local v2 raw refs (current + archived generations)
+git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/*'
+# Verify legacy v1 branch presence for fallback tests
+git show-ref --verify -- refs/heads/entire/checkpoints/v1 || echo "v1 checkpoints branch not found"
+```
+
+## Shared Inspection Toolkit
+
+### Ref checks
+
+```bash
+# Local v2 metadata ref hash (if present)
+git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Local v2 raw current ref hash (if present)
+git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# All local v2 raw refs with object IDs
+git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
+# Remote view of all v2 refs (origin)
+git ls-remote origin 'refs/entire/checkpoints/v2/*'
+```
+
+### Checkpoint shard helper
+
+Use the reusable executable script to determine the shard path.
+
+```bash
+# Create helper script
+cat > scripts/checkpoint-shard-path <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+checkpoint_id="${1:-}"
+if [ -z "$checkpoint_id" ]; then
+  echo "usage: checkpoint-shard-path <checkpoint-id>" >&2
+  exit 1
+fi
+
+echo "${checkpoint_id:0:2}/${checkpoint_id:2}"
+EOF
+
+# Make executable
+chmod +x scripts/checkpoint-shard-path
+
+# Usage
+checkpoint_id="a3b2c4d5e6f7"
+shard_path="$(scripts/checkpoint-shard-path "$checkpoint_id")"
+echo "$shard_path"
+```
+
+### Tree/file checks
+
+```bash
+# Show checkpoint directory in v2 permanent ref
+git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path" || echo "checkpoint path not found on v2 main"
+# Show checkpoint directory in v2 raw current generation
+git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path" || echo "checkpoint path not found on v2 full/current"
+# Read checkpoint summary metadata
+git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json" || echo "metadata.json not found on v2 main"
+# Read compact transcript (if compaction is available)
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
+# Read raw transcript used by resume
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
+# Read hash for raw transcript integrity
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/content_hash.txt" || echo "content_hash.txt not found on v2 full/current"
+```
+
+### Archived generation checks
+
+```bash
+# List archived raw generations
+git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
+# Inspect generation retention timestamps
+git show refs/entire/checkpoints/v2/full/0000000000001:generation.json || echo "generation.json not found for archived generation"
+# Check whether checkpoint exists in a specific archived generation
+git ls-tree --name-only refs/entire/checkpoints/v2/full/0000000000001 "$shard_path" || echo "checkpoint path not found in archived generation"
+```
+
+### v1 fallback checks
+
+```bash
+# Verify legacy v1 metadata branch exists (for fallback)
+git show-ref --verify -- refs/heads/entire/checkpoints/v1 || echo "v1 checkpoints branch not found"
+# Check checkpoint path on v1 branch
+git ls-tree --name-only entire/checkpoints/v1 "$shard_path" || echo "checkpoint path not found on v1"
+# Read raw transcript from v1
+git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v1"
+```
+
+## Custom Ref Primer (for this guide)
+
+Use this section when a scenario asks you to add/remove or inspect v2 refs directly.
+
+```bash
+# List local v2 refs
+git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/*'
+
+# Delete one local ref (safe in disposable clone)
+git update-ref -d refs/entire/checkpoints/v2/main
+
+# Delete another local ref
+git update-ref -d refs/entire/checkpoints/v2/full/current
+
+# Delete all local archived generation refs
+for ref in $(git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'); do
+  git update-ref -d "$ref"
+done
+
+# Verify what still exists locally
+git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/*'
+
+# Verify what exists on origin (remote refs are unchanged by local delete)
+git ls-remote origin 'refs/entire/checkpoints/v2/*'
+```
+
+Notes:
+- `git update-ref -d <ref>` deletes a **local ref pointer** only; it does not delete objects from remote.
+- Destructive ref setup means intentionally deleting local checkpoint refs to simulate missing-data scenarios.
+- Do this only in `repo-fresh` (or another disposable clone) so you do not lose local checkpoint state in your primary working clone.
+- If you accidentally delete refs in the wrong clone, recover by fetching them again:
+
+```bash
+git fetch origin refs/entire/checkpoints/v2/main:refs/entire/checkpoints/v2/main
+git fetch origin refs/entire/checkpoints/v2/full/current:refs/entire/checkpoints/v2/full/current
+```
+
+## Command Test Plan
+
+This guide is intentionally command-first. Each command section below includes self-contained setup, execution, checks, and expected outcomes.
+
+---
+
+## 1) `entire resume`
+
+- What it does: restores the session transcript and prints the resume command.
+- Use it for: continuing work from a checkpointed branch/session.
+
+### Scenario 1: Baseline v2 resume
+
+Setup:
+1. In `repo-a`, enable `checkpoints_v2=true` and `push_v2_refs=true`.
+2. Create a feature branch and produce at least one checkpoint.
+3. Switch away from the feature branch.
+
+Run:
+1. Execute `entire resume <feature-branch>`.
+
+Checks:
+
+```bash
+# Confirm local v2 metadata ref state before/after resume
+git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Confirm local v2 raw current ref state before/after resume
+git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# List all local raw refs to verify archived generation visibility
+git for-each-ref --format='%(refname:short)' 'refs/entire/checkpoints/v2/full/*'
+# Check remote metadata ref availability
+git ls-remote origin 'refs/entire/checkpoints/v2/main'
+# Check remote raw refs availability
+git ls-remote origin 'refs/entire/checkpoints/v2/full/*'
+```
+
+Expected:
+- Session restored and resume command printed.
+- Checkpoint data resolves from v2 (`/full/current`).
+
+### Scenario 2: Resume from archived generation
+
+Setup:
+1. In `repo-a`, generate enough checkpoints to rotate `/full/current`.
+2. Identify a checkpoint from before rotation.
+
+Run:
+1. Execute `entire resume <branch-containing-older-checkpoint>`.
+
+Expected:
+- Resume succeeds using raw transcript from an archived `refs/entire/checkpoints/v2/full/<generation>` ref.
+
+### Scenario 3: Local missing, remote present
+
+Setup:
+1. Use `repo-fresh` clone (preferred), or delete local v2 refs in disposable clone.
+2. Confirm refs exist on remote.
+
+```bash
+git update-ref -d refs/entire/checkpoints/v2/main
+git update-ref -d refs/entire/checkpoints/v2/full/current
+for ref in $(git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'); do
+  git update-ref -d "$ref"
+done
+git ls-remote origin 'refs/entire/checkpoints/v2/*'
+```
+
+Run:
+1. Execute `entire resume <feature-branch>`.
+
+Expected:
+- Resume fetches required data and succeeds when remote data exists.
+
+### Scenario 4: `checkpoint_remote` source
+
+Setup:
+1. Configure `checkpoint_remote`.
+2. Ensure v2 refs exist on checkpoint remote and not on origin.
+
+Run:
+1. Execute `entire resume <feature-branch>`.
+
+Expected:
+- Resume succeeds by fetching metadata/transcripts from checkpoint remote.
+
+### Scenario 5: v1 fallback
+
+Setup:
+1. Create checkpoint with `checkpoints_v2=false`.
+2. Enable `checkpoints_v2=true` afterward.
+
+Run:
+1. Execute `entire resume <branch-with-v1-only-checkpoint>`.
+
+Expected:
+- Resume succeeds via v1 fallback path.
+
+### Pass checklist
+
+- [ ] Baseline v2 resume validated.
+- [ ] Archived-generation lookup validated.
+- [ ] Missing-local fetch validated.
+- [ ] `checkpoint_remote` path validated.
+- [ ] v1 fallback validated.
+
+---
+
+## 2) `entire explain`
+
+- What it does: reads checkpoint transcript data and explains context.
+- Use it for: understanding what changed and why at a checkpoint.
+
+### Scenario 1: Compact transcript on `/main`
+
+Setup:
+1. Create a checkpoint where compact transcript exists on `/main`.
+
+Run:
+1. Execute `entire explain <checkpoint-id-or-target>`.
+
+Checks:
+
+```bash
+# Compact transcript on /main (preferred explain source)
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
+# Raw transcript on v2 (fallback source)
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
+# Raw transcript on v1 (legacy fallback source)
+git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v1"
+```
+
+Expected:
+- Explain uses `transcript.jsonl` from `/main`.
+
+### Scenario 2: Fallback to raw transcript
+
+Setup:
+1. Create or identify a checkpoint where compact transcript is intentionally unavailable.
+2. Recommended setup path:
+   - Use an external agent/plugin that does **not** advertise `compact_transcript` capability.
+   - Create one checkpoint with `checkpoints_v2=true`.
+3. Verify setup before running explain:
+
+```bash
+# compact transcript should be absent for this checkpoint
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
+# raw transcript should exist
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
+```
+
+Run:
+1. Execute `entire explain <checkpoint-id-or-target>`.
+
+Expected:
+- Explain falls back to raw transcript in `/full/*`.
+
+### Scenario 3: Local missing / remote present
+
+Setup:
+1. Remove local v2 refs in disposable clone or use `repo-fresh`.
+
+Run:
+1. Execute `entire explain <target>`.
+
+Expected:
+- Explain succeeds after fetching from remote.
+
+### Scenario 4: v1 fallback
+
+Setup:
+1. Use branch/checkpoint where data exists only in v1.
+
+Run:
+1. Execute `entire explain <target>`.
+
+Expected:
+- Explain succeeds via v1 fallback.
+
+### Pass checklist
+
+- [ ] Compact transcript preferred when present.
+- [ ] Raw fallback validated.
+- [ ] v1 fallback validated.
+
+---
+
+## 3) `entire doctor`
+
+- What it does: validates checkpoint refs and metadata consistency.
+- Use it for: troubleshooting missing/corrupt checkpoint state.
+
+### Scenario 1: Healthy repository
+
+Setup:
+1. Ensure v2 refs exist and are readable.
+
+Run:
+1. Execute `entire doctor`.
+
+Checks:
+
+```bash
+# Validate presence/absence of v2 metadata ref
+git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Validate presence/absence of v2 raw current ref
+git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# Enumerate all raw refs checked by doctor
+git for-each-ref --format='%(refname:short)' 'refs/entire/checkpoints/v2/full/*'
+# Inspect archived generation metadata health
+git show refs/entire/checkpoints/v2/full/0000000000001:generation.json || echo "generation.json not found for archived generation"
+```
+
+Expected:
+- Doctor reports healthy checkpoint/ref state.
+
+### Scenario 2: Missing refs
+
+Setup:
+1. In disposable clone, delete `/main` and/or `/full/current` ref.
+
+```bash
+# Delete local v2 refs to simulate missing-ref state
+git update-ref -d refs/entire/checkpoints/v2/main
+git update-ref -d refs/entire/checkpoints/v2/full/current
+
+# Confirm they are missing locally
+git show-ref --verify -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+git show-ref --verify -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+```
+
+Run:
+1. Execute `entire doctor`.
+
+Expected:
+- Doctor reports missing refs with actionable guidance.
+
+### Pass checklist
+
+- [ ] Healthy case passes with no false positives.
+- [ ] Missing-ref diagnostics are detected with actionable guidance.
+
+---
+
+## 4) `entire clean`
+
+- What it does: removes retention-expired archived raw transcript generations.
+- Use it for: storage cleanup while preserving permanent checkpoint metadata.
+
+### Scenario 1: No eligible generations
+
+Setup:
+1. Ensure archived generations exist but none are older than retention window.
+
+Run:
+1. Execute `entire clean`.
+
+Checks:
+
+```bash
+# Ensure permanent ref is unchanged by clean
+git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Ensure active raw ref is unchanged by clean
+git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# Compare archived generation refs before/after clean
+git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
+# Compare remote archived refs before/after clean
+git ls-remote origin 'refs/entire/checkpoints/v2/full/*'
+# Read retention timestamps used for deletion eligibility
+git show refs/entire/checkpoints/v2/full/0000000000001:generation.json || echo "generation.json not found for archived generation"
+```
+
+Expected:
+- No archived refs are deleted.
+
+### Scenario 2: Eligible generation deletion
+
+Setup:
+1. Make at least one archived generation retention-eligible.
+
+Run:
+1. Execute `entire clean`.
+
+Expected:
+- Only eligible archived refs are deleted.
+
+### Scenario 3: Mixed eligibility
+
+Setup:
+1. Have at least two archived generations, one eligible and one not.
+
+Run:
+1. Execute `entire clean`.
+
+Expected:
+- Eligible generation removed; non-eligible remains.
+
+### Scenario 4: Remote deletion behavior
+
+Setup:
+1. Configure origin or `checkpoint_remote` for v2 ref pushes.
+
+Run:
+1. Execute `entire clean`.
+
+Expected:
+- Remote archived refs match local deletions.
+
+### Pass checklist
+
+- [ ] Retention eligibility matches configuration.
+- [ ] `/main` and `/full/current` unchanged.
+- [ ] Local and remote deletion results match expected behavior.
+
+---
+
+## 5) `entire migrate`
+
+- What it does: migrates v1 checkpoint storage into v2 split refs.
+- Use it for: upgrading repositories with existing v1 checkpoint history.
+
+### Scenario 1: First migration run
+
+Setup:
+1. Prepare repository with v1-only checkpoint history.
+
+Run:
+1. Execute `entire migrate`.
+
+Checks:
+
+```bash
+# Verify legacy v1 source branch exists prior to migration
+git show-ref --verify -- refs/heads/entire/checkpoints/v1 || echo "v1 checkpoints branch not found"
+# Verify v2 metadata ref after migration
+git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Verify v2 raw current ref after migration
+git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# Confirm checkpoint path exists on /main
+git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path" || echo "checkpoint path not found on v2 main"
+# Confirm checkpoint path exists on /full/current
+git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path" || echo "checkpoint path not found on v2 full/current"
+# Validate migrated checkpoint summary metadata
+git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json" || echo "metadata.json not found on v2 main"
+# Validate migrated prompt artifact
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/prompt.txt" || echo "prompt.txt not found on v2 main"
+# Validate migrated compact transcript (if available)
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
+# Validate migrated raw transcript
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
+```
+
+Expected:
+- v1 checkpoints are migrated to v2 split refs.
+
+### Scenario 2: Idempotency
+
+Setup:
+1. Keep repository unchanged after first migrate run.
+
+Run:
+1. Execute `entire migrate` again.
+
+Expected:
+- No duplicate logical checkpoint entries.
+
+### Scenario 3: Non-compaction path
+
+Setup:
+1. Use checkpoint data where compaction is unavailable.
+
+Run:
+1. Execute `entire migrate`.
+
+Expected:
+- `/main` has metadata/prompt (and no compact transcript), `/full/*` has raw transcript.
+
+### Pass checklist
+
+- [ ] Migration output correctness validated.
+- [ ] Idempotency validated.
+- [ ] Task metadata continuity validated.
+
+---
+
+## 6) `entire status` (regression guard)
+
+- What it does: reports current session status/phase information.
+- Use it for: quick health checks independent of committed checkpoint refs.
+
+### Scenario 1: Baseline status behavior
+
+Setup:
+1. In `repo-a`, run normal session flow and create at least one checkpoint.
+
+Run:
+1. Execute `entire status`.
+
+Expected:
+- Status output reflects current session/phase accurately.
+
+### Scenario 2: Status with missing local v2 refs
+
+Setup:
+1. In disposable clone, remove local v2 refs.
+
+```bash
+# Remove local v2 refs to prove status does not depend on them
+git update-ref -d refs/entire/checkpoints/v2/main
+git update-ref -d refs/entire/checkpoints/v2/full/current
+for ref in $(git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'); do
+  git update-ref -d "$ref"
+done
+```
+
+Run:
+1. Execute `entire status`.
+
+Expected:
+- Status remains functional and does not depend on committed v2 refs.
+
+### Pass checklist
+
+- [ ] Status remains correct before/after v2 writes.
+- [ ] Status remains functional when local v2 refs are absent.
+
+---
+
+## 7) `entire rewind` (regression guard)
+
+- What it does: restores repository files/logs to a prior checkpoint.
+- Use it for: undoing recent changes and returning to earlier state.
+
+### Scenario 1: Rewind normal flow
+
+Setup:
+1. Create at least two temporary checkpoints in one session.
+2. Modify files between checkpoints.
+
+Run:
+1. Execute `entire rewind` and select an earlier checkpoint.
+
+Expected:
+- Files and prompt/log context restore to selected checkpoint state.
+
+### Pass checklist
+
+- [ ] Rewind still restores expected files and prompt context.
+
+## Evidence Collection (for every run)
+
+Capture:
+- executed command + full output
+- before/after `git show-ref` snapshots
+- `git ls-remote` snapshots when remote behavior is involved
+- `git show` and `git ls-tree` evidence for expected files/paths
+- outcome classification: pass/fail/blocked with reason
+
+## Exit Criteria
+
+Migration manual validation is complete when:
+- `resume`, `explain`, `doctor`, `clean`, and `migrate` pass applicable scenarios
+- remote fetch and `checkpoint_remote` paths pass in missing-local situations
+- rotation and cleanup lifecycle pass without violating `/main` permanence
+- `status` and `rewind` show no regressions

From e274cfba2c7dfdd26975399e22655cd0d50ed40d Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Thu, 2 Apr 2026 17:35:09 -0700
Subject: [PATCH 02/17] docs: streamline checkpoint test guide command blocks

Entire-Checkpoint: fc81cbd6d899
---
 .../guides/checkpoints-v2-manual-test-plan.md | 203 ++++++++++--------
 1 file changed, 108 insertions(+), 95 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 5d6c3d64e6..c46fb3cbd3 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -45,37 +45,40 @@ Set strategy options in `.entire/settings.json`:
 ### Baseline checks (run before each command section)
 
 ```bash
-# Verify v2 metadata ref exists locally (or not, for fallback scenarios)
-git show-ref --verify -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
+# Verify v2 metadata ref exists locally
+git show-ref --verify -- refs/entire/checkpoints/v2/main
 # Verify v2 raw current-generation ref exists locally
-git show-ref --verify -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+git show-ref --verify -- refs/entire/checkpoints/v2/full/current
 # List all local v2 raw refs (current + archived generations)
 git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/*'
-# Verify legacy v1 branch presence for fallback tests
-git show-ref --verify -- refs/heads/entire/checkpoints/v1 || echo "v1 checkpoints branch not found"
+# Verify legacy v1 branch exists for fallback tests
+git show-ref --verify -- refs/heads/entire/checkpoints/v1
 ```
 
 ## Shared Inspection Toolkit
 
 ### Ref checks
 
+Use this block to inspect local and remote v2 ref state.
+
 ```bash
-# Local v2 metadata ref hash (if present)
-git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
-# Local v2 raw current ref hash (if present)
-git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+# Local v2 metadata ref hash
+git show-ref -- refs/entire/checkpoints/v2/main
+# Local v2 raw current ref hash
+git show-ref -- refs/entire/checkpoints/v2/full/current
 # All local v2 raw refs with object IDs
 git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
-# Remote view of all v2 refs (origin)
+# Remote view of all v2 refs on origin
 git ls-remote origin 'refs/entire/checkpoints/v2/*'
 ```
 
 ### Checkpoint shard helper
 
+Use this helper to derive `<shard_path>` from a checkpoint ID.
+
 Use the reusable executable script to determine the shard path.
 
 ```bash
-# Create helper script
 cat > scripts/checkpoint-shard-path <<'EOF'
 #!/usr/bin/env bash
 set -euo pipefail
@@ -89,10 +92,8 @@ fi
 echo "${checkpoint_id:0:2}/${checkpoint_id:2}"
 EOF
 
-# Make executable
 chmod +x scripts/checkpoint-shard-path
 
-# Usage
 checkpoint_id="a3b2c4d5e6f7"
 shard_path="$(scripts/checkpoint-shard-path "$checkpoint_id")"
 echo "$shard_path"
@@ -100,41 +101,47 @@ echo "$shard_path"
 
 ### Tree/file checks
 
+Use this block to inspect checkpoint files on v2 refs.
+
 ```bash
-# Show checkpoint directory in v2 permanent ref
-git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path" || echo "checkpoint path not found on v2 main"
-# Show checkpoint directory in v2 raw current generation
-git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path" || echo "checkpoint path not found on v2 full/current"
+# List checkpoint subtree in v2 permanent ref
+git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path"
+# List checkpoint subtree in v2 raw current ref
+git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path"
 # Read checkpoint summary metadata
-git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json" || echo "metadata.json not found on v2 main"
-# Read compact transcript (if compaction is available)
-git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
-# Read raw transcript used by resume
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
-# Read hash for raw transcript integrity
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/content_hash.txt" || echo "content_hash.txt not found on v2 full/current"
+git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
+# Read compact transcript (when available)
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
+# Read raw transcript
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
+# Read raw transcript content hash
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/content_hash.txt"
 ```
 
 ### Archived generation checks
 
+Use this block to inspect archived v2 raw generations.
+
 ```bash
-# List archived raw generations
+# List archived v2 raw generation refs
 git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
-# Inspect generation retention timestamps
-git show refs/entire/checkpoints/v2/full/0000000000001:generation.json || echo "generation.json not found for archived generation"
-# Check whether checkpoint exists in a specific archived generation
-git ls-tree --name-only refs/entire/checkpoints/v2/full/0000000000001 "$shard_path" || echo "checkpoint path not found in archived generation"
+# Read generation metadata for retention validation
+git show refs/entire/checkpoints/v2/full/0000000000001:generation.json
+# Check if a checkpoint exists in a specific archived generation
+git ls-tree --name-only refs/entire/checkpoints/v2/full/0000000000001 "$shard_path"
 ```
 
 ### v1 fallback checks
 
+Use this block to inspect legacy v1 fallback data.
+
 ```bash
-# Verify legacy v1 metadata branch exists (for fallback)
-git show-ref --verify -- refs/heads/entire/checkpoints/v1 || echo "v1 checkpoints branch not found"
-# Check checkpoint path on v1 branch
-git ls-tree --name-only entire/checkpoints/v1 "$shard_path" || echo "checkpoint path not found on v1"
-# Read raw transcript from v1
-git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v1"
+# Verify v1 checkpoint branch exists
+git show-ref --verify -- refs/heads/entire/checkpoints/v1
+# Check checkpoint shard path on v1
+git ls-tree --name-only entire/checkpoints/v1 "$shard_path"
+# Read raw transcript from v1 fallback
+git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl"
 ```
 
 ## Custom Ref Primer (for this guide)
@@ -198,16 +205,14 @@ Run:
 Checks:
 
 ```bash
-# Confirm local v2 metadata ref state before/after resume
-git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
-# Confirm local v2 raw current ref state before/after resume
-git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
-# List all local raw refs to verify archived generation visibility
-git for-each-ref --format='%(refname:short)' 'refs/entire/checkpoints/v2/full/*'
-# Check remote metadata ref availability
-git ls-remote origin 'refs/entire/checkpoints/v2/main'
-# Check remote raw refs availability
-git ls-remote origin 'refs/entire/checkpoints/v2/full/*'
+# Local v2 metadata ref hash
+git show-ref -- refs/entire/checkpoints/v2/main
+# Local v2 raw current ref hash
+git show-ref -- refs/entire/checkpoints/v2/full/current
+# All local v2 raw refs with object IDs
+git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
+# Remote view of all v2 refs on origin
+git ls-remote origin 'refs/entire/checkpoints/v2/*'
 ```
 
 Expected:
@@ -297,12 +302,12 @@ Run:
 Checks:
 
 ```bash
-# Compact transcript on /main (preferred explain source)
-git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
-# Raw transcript on v2 (fallback source)
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
-# Raw transcript on v1 (legacy fallback source)
-git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v1"
+# Read compact transcript (when available)
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
+# Read raw transcript
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
+# Read raw transcript from v1 fallback
+git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl"
 ```
 
 Expected:
@@ -318,10 +323,8 @@ Setup:
 3. Verify setup before running explain:
 
 ```bash
-# compact transcript should be absent for this checkpoint
-git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
-# raw transcript should exist
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
 ```
 
 Run:
@@ -376,14 +379,16 @@ Run:
 Checks:
 
 ```bash
-# Validate presence/absence of v2 metadata ref
-git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
-# Validate presence/absence of v2 raw current ref
-git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
-# Enumerate all raw refs checked by doctor
-git for-each-ref --format='%(refname:short)' 'refs/entire/checkpoints/v2/full/*'
-# Inspect archived generation metadata health
-git show refs/entire/checkpoints/v2/full/0000000000001:generation.json || echo "generation.json not found for archived generation"
+# Local v2 metadata ref hash
+git show-ref -- refs/entire/checkpoints/v2/main
+# Local v2 raw current ref hash
+git show-ref -- refs/entire/checkpoints/v2/full/current
+# All local v2 raw refs with object IDs
+git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
+# List archived v2 raw generation refs
+git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
+# Read generation metadata for retention validation
+git show refs/entire/checkpoints/v2/full/0000000000001:generation.json
 ```
 
 Expected:
@@ -395,13 +400,11 @@ Setup:
 1. In disposable clone, delete `/main` and/or `/full/current` ref.
 
 ```bash
-# Delete local v2 refs to simulate missing-ref state
 git update-ref -d refs/entire/checkpoints/v2/main
 git update-ref -d refs/entire/checkpoints/v2/full/current
 
-# Confirm they are missing locally
-git show-ref --verify -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
-git show-ref --verify -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
+git show-ref --verify -- refs/entire/checkpoints/v2/main
+git show-ref --verify -- refs/entire/checkpoints/v2/full/current
 ```
 
 Run:
@@ -431,18 +434,21 @@ Run:
 1. Execute `entire clean`.
 
 Checks:
+Run this block before and after `entire clean`:
 
 ```bash
-# Ensure permanent ref is unchanged by clean
-git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
-# Ensure active raw ref is unchanged by clean
-git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
-# Compare archived generation refs before/after clean
-git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
-# Compare remote archived refs before/after clean
+# Local v2 metadata ref hash
+git show-ref -- refs/entire/checkpoints/v2/main
+# Local v2 raw current ref hash
+git show-ref -- refs/entire/checkpoints/v2/full/current
+# All local v2 raw refs with object IDs
+git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
+# Remote view of archived v2 refs on origin
 git ls-remote origin 'refs/entire/checkpoints/v2/full/*'
-# Read retention timestamps used for deletion eligibility
-git show refs/entire/checkpoints/v2/full/0000000000001:generation.json || echo "generation.json not found for archived generation"
+# List archived v2 raw generation refs
+git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
+# Read generation metadata for retention validation
+git show refs/entire/checkpoints/v2/full/0000000000001:generation.json
 ```
 
 Expected:
@@ -503,26 +509,34 @@ Run:
 1. Execute `entire migrate`.
 
 Checks:
+Run this block before migration:
 
 ```bash
-# Verify legacy v1 source branch exists prior to migration
-git show-ref --verify -- refs/heads/entire/checkpoints/v1 || echo "v1 checkpoints branch not found"
-# Verify v2 metadata ref after migration
-git show-ref -- refs/entire/checkpoints/v2/main || echo "v2 main ref not found"
-# Verify v2 raw current ref after migration
-git show-ref -- refs/entire/checkpoints/v2/full/current || echo "v2 full/current ref not found"
-# Confirm checkpoint path exists on /main
-git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path" || echo "checkpoint path not found on v2 main"
-# Confirm checkpoint path exists on /full/current
-git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path" || echo "checkpoint path not found on v2 full/current"
-# Validate migrated checkpoint summary metadata
-git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json" || echo "metadata.json not found on v2 main"
-# Validate migrated prompt artifact
-git show "refs/entire/checkpoints/v2/main:${shard_path}/0/prompt.txt" || echo "prompt.txt not found on v2 main"
-# Validate migrated compact transcript (if available)
-git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl" || echo "transcript.jsonl not found on v2 main"
-# Validate migrated raw transcript
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl" || echo "full.jsonl not found on v2 full/current"
+# Verify v1 checkpoint branch exists
+git show-ref --verify -- refs/heads/entire/checkpoints/v1
+# Check checkpoint shard path on v1
+git ls-tree --name-only entire/checkpoints/v1 "$shard_path"
+# Read raw transcript from v1 fallback
+git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl"
+```
+
+Run this block after migration:
+
+```bash
+# Local v2 metadata ref hash
+git show-ref -- refs/entire/checkpoints/v2/main
+# Local v2 raw current ref hash
+git show-ref -- refs/entire/checkpoints/v2/full/current
+# List checkpoint subtree in v2 permanent ref
+git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path"
+# List checkpoint subtree in v2 raw current ref
+git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path"
+# Read checkpoint summary metadata
+git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
+# Read compact transcript (when available)
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
+# Read raw transcript
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
 ```
 
 Expected:
@@ -580,7 +594,6 @@ Setup:
 1. In disposable clone, remove local v2 refs.
 
 ```bash
-# Remove local v2 refs to prove status does not depend on them
 git update-ref -d refs/entire/checkpoints/v2/main
 git update-ref -d refs/entire/checkpoints/v2/full/current
 for ref in $(git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'); do

From f4a1695a86cdea0a370baefcd201fa6fcb03c7dd Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Thu, 2 Apr 2026 17:39:59 -0700
Subject: [PATCH 03/17] docs: note migrate command is not yet implemented

Entire-Checkpoint: c8f2b08cbc4c
---
 docs/guides/checkpoints-v2-manual-test-plan.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index c46fb3cbd3..f167617781 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -500,6 +500,8 @@ Expected:
 - What it does: migrates v1 checkpoint storage into v2 split refs.
 - Use it for: upgrading repositories with existing v1 checkpoint history.
 
+Note: `entire migrate` is not implemented yet. Treat this section as a forward-looking validation plan and run it only after the command becomes available.
+
 ### Scenario 1: First migration run
 
 Setup:

From 2697608a1bc43daa248e6034a0d630addd80d59a Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Thu, 2 Apr 2026 17:49:14 -0700
Subject: [PATCH 04/17] review: align clean scenarios with current command
 behavior

Entire-Checkpoint: f5a5d8076f46
---
 .../guides/checkpoints-v2-manual-test-plan.md | 80 +++++++++++--------
 1 file changed, 46 insertions(+), 34 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index f167617781..d772d333aa 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -422,76 +422,88 @@ Expected:
 
 ## 4) `entire clean`
 
-- What it does: removes retention-expired archived raw transcript generations.
-- Use it for: storage cleanup while preserving permanent checkpoint metadata.
+- What it does: cleans session state and shadow branch data for current HEAD, or orphaned Entire data with `--all`.
+- Use it for: removing stale session metadata and orphaned Entire artifacts.
 
-### Scenario 1: No eligible generations
+### Scenario 1: Current HEAD cleanup
 
 Setup:
-1. Ensure archived generations exist but none are older than retention window.
+1. In `repo-a`, create a session on the current HEAD so there is session state and shadow-branch data.
 
 Run:
-1. Execute `entire clean`.
+1. Execute `entire clean --dry-run` and review the preview.
+2. Execute `entire clean` and confirm the prompt.
 
 Checks:
-Run this block before and after `entire clean`:
 
 ```bash
-# Local v2 metadata ref hash
-git show-ref -- refs/entire/checkpoints/v2/main
-# Local v2 raw current ref hash
-git show-ref -- refs/entire/checkpoints/v2/full/current
-# All local v2 raw refs with object IDs
-git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
-# Remote view of archived v2 refs on origin
-git ls-remote origin 'refs/entire/checkpoints/v2/full/*'
-# List archived v2 raw generation refs
-git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
-# Read generation metadata for retention validation
-git show refs/entire/checkpoints/v2/full/0000000000001:generation.json
+# List shadow branches before/after
+git branch --list 'entire/*'
+# List local session state files before/after
+ls .git/entire-sessions
 ```
 
 Expected:
-- No archived refs are deleted.
+- `--dry-run` lists items without deleting.
+- `entire clean` removes current-HEAD session state and shadow branch data.
 
-### Scenario 2: Eligible generation deletion
+### Scenario 2: Active-session guard and `--force`
 
 Setup:
-1. Make at least one archived generation retention-eligible.
+1. Start an active session on current HEAD.
 
 Run:
-1. Execute `entire clean`.
+1. Execute `entire clean` without `--force`.
+2. Execute `entire clean --force`.
 
 Expected:
-- Only eligible archived refs are deleted.
+- Without `--force`, command warns and refuses to clean active session data.
+- With `--force`, command proceeds.
 
-### Scenario 3: Mixed eligibility
+### Scenario 3: Repository-wide orphan cleanup (`--all`)
 
 Setup:
-1. Have at least two archived generations, one eligible and one not.
+1. Create orphaned data (e.g., old shadow branches, orphaned session-state files, or orphaned checkpoint entries on `entire/checkpoints/v1`).
 
 Run:
-1. Execute `entire clean`.
+1. Execute `entire clean --all --dry-run`.
+2. Execute `entire clean --all`.
+
+Checks:
+
+```bash
+# List shadow branches before/after --all
+git branch --list 'entire/*'
+# Inspect session state files before/after --all
+ls .git/entire-sessions
+# Inspect metadata branch tip commit before/after --all
+git log --oneline -1 entire/checkpoints/v1
+```
 
 Expected:
-- Eligible generation removed; non-eligible remains.
+- Dry-run previews orphaned items.
+- `--all` removes orphaned items and temporary files.
+- `entire/checkpoints/v1` branch is preserved.
 
-### Scenario 4: Remote deletion behavior
+### Scenario 4: Single-session cleanup (`--session`)
 
 Setup:
-1. Configure origin or `checkpoint_remote` for v2 ref pushes.
+1. Ensure at least one known session ID exists.
 
 Run:
-1. Execute `entire clean`.
+1. Execute `entire clean --session <session-id> --dry-run`.
+2. Execute `entire clean --session <session-id>`.
 
 Expected:
-- Remote archived refs match local deletions.
+- Only the specified session is cleaned.
+- File changes remain in working directory (metadata/session cleanup only).
 
 ### Pass checklist
 
-- [ ] Retention eligibility matches configuration.
-- [ ] `/main` and `/full/current` unchanged.
-- [ ] Local and remote deletion results match expected behavior.
+- [ ] Current-HEAD cleanup behavior validated.
+- [ ] Active-session guard and `--force` behavior validated.
+- [ ] `--all` orphan cleanup behavior validated.
+- [ ] `--session` cleanup behavior validated.
 
 ---
 

From c94d4e853f3deb43151fdfd4103ddefb08715f0d Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Thu, 2 Apr 2026 17:49:59 -0700
Subject: [PATCH 05/17] review: align doctor scenarios with current command
 behavior

Entire-Checkpoint: 4ac0fc5b43c4
---
 .../guides/checkpoints-v2-manual-test-plan.md | 67 ++++++++++++-------
 1 file changed, 42 insertions(+), 25 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index d772d333aa..e7ed924ea2 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -365,13 +365,15 @@ Expected:
 
 ## 3) `entire doctor`
 
-- What it does: validates checkpoint refs and metadata consistency.
-- Use it for: troubleshooting missing/corrupt checkpoint state.
+- What it does: diagnoses and fixes disconnected `entire/checkpoints/v1` metadata branches and stuck sessions.
+- Use it for: recovering from session-state/shadow-branch issues and metadata-branch divergence.
 
-### Scenario 1: Healthy repository
+### Scenario 1: No issues detected
 
 Setup:
-1. Ensure v2 refs exist and are readable.
+1. Ensure no stale sessions are stuck in `ACTIVE` for >1h.
+2. Ensure no `ENDED` sessions have uncondensed checkpoint data.
+3. Ensure local and remote `entire/checkpoints/v1` are connected.
 
 Run:
 1. Execute `entire doctor`.
@@ -379,44 +381,59 @@ Run:
 Checks:
 
 ```bash
-# Local v2 metadata ref hash
-git show-ref -- refs/entire/checkpoints/v2/main
-# Local v2 raw current ref hash
-git show-ref -- refs/entire/checkpoints/v2/full/current
-# All local v2 raw refs with object IDs
-git for-each-ref --format='%(refname:short) %(objectname)' 'refs/entire/checkpoints/v2/full/*'
-# List archived v2 raw generation refs
-git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'
-# Read generation metadata for retention validation
-git show refs/entire/checkpoints/v2/full/0000000000001:generation.json
+# List current session states
+ls .git/entire-sessions
+# List shadow branches
+git branch --list 'entire/*'
+# Inspect local metadata branch tip
+git log --oneline -1 entire/checkpoints/v1
+# Inspect remote metadata branch tip
+git ls-remote origin refs/heads/entire/checkpoints/v1
 ```
 
 Expected:
-- Doctor reports healthy checkpoint/ref state.
+- Doctor reports no disconnected metadata issue and no stuck sessions.
 
-### Scenario 2: Missing refs
+### Scenario 2: Stuck session handling
 
 Setup:
-1. In disposable clone, delete `/main` and/or `/full/current` ref.
+1. Create a session in `ACTIVE` and make it stale (or create an `ENDED` session with uncondensed data).
+2. Confirm session state file and shadow branch exist.
 
 ```bash
-git update-ref -d refs/entire/checkpoints/v2/main
-git update-ref -d refs/entire/checkpoints/v2/full/current
-
-git show-ref --verify -- refs/entire/checkpoints/v2/main
-git show-ref --verify -- refs/entire/checkpoints/v2/full/current
+# Session states present
+ls .git/entire-sessions
+# Shadow branches present
+git branch --list 'entire/*'
 ```
 
 Run:
 1. Execute `entire doctor`.
+2. Choose `Condense`, `Discard`, or `Skip` at the prompt (or use `--force` for auto-fix).
+
+Expected:
+- Doctor detects stuck sessions and applies selected remediation.
+- After condense/discard, corresponding session state/shadow-branch data is reduced or removed.
+
+### Scenario 3: Disconnected metadata branch repair
+
+Setup:
+1. Create local/remote `entire/checkpoints/v1` branches with no common ancestor (use disposable repo).
+
+Run:
+1. Execute `entire doctor`.
+2. Approve metadata repair when prompted (or run with `--force`).
 
 Expected:
-- Doctor reports missing refs with actionable guidance.
+- Doctor detects disconnected metadata branch state.
+- Doctor repairs by reconciling local checkpoints onto remote tip.
+- Local and remote metadata branches become connected.
 
 ### Pass checklist
 
-- [ ] Healthy case passes with no false positives.
-- [ ] Missing-ref diagnostics are detected with actionable guidance.
+- [ ] No-issue case reports clean status.
+- [ ] Stuck-session detection and remediation validated.
+- [ ] Disconnected metadata-branch repair validated.
 
 ---
 

From 69380cce8cf4d3344f1432091c6400c0c6b232dd Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Thu, 2 Apr 2026 17:53:19 -0700
Subject: [PATCH 06/17] review: add attach command validation section

Entire-Checkpoint: ea6515ad2878
---
 .../guides/checkpoints-v2-manual-test-plan.md | 80 ++++++++++++++++++-
 1 file changed, 77 insertions(+), 3 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index e7ed924ea2..502443fe05 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -603,7 +603,81 @@ Expected:
 
 ---
 
-## 6) `entire status` (regression guard)
+## 6) `entire attach`
+
+- What it does: attaches an existing agent transcript/session to checkpoint metadata when hooks did not capture it.
+- Use it for: recovering missed checkpoints or linking research sessions to the latest commit.
+
+### Scenario 1: Attach creates a new checkpoint and trailer
+
+Setup:
+1. Ensure repository has at least one commit.
+2. Ensure target session transcript exists on disk for the selected agent.
+3. Ensure latest commit does not already contain `Entire-Checkpoint` trailer.
+
+Run:
+1. Execute `entire attach <session-id> --agent <agent-name>`.
+2. When prompted, allow trailer amendment (or rerun with `--force`).
+
+Checks:
+
+```bash
+# Verify latest commit includes Entire-Checkpoint trailer
+git log -1 --pretty=%B
+# Verify checkpoint metadata exists on v1 branch
+git show-ref --verify -- refs/heads/entire/checkpoints/v1
+```
+
+Expected:
+- Attach reports a created checkpoint ID.
+- Latest commit includes `Entire-Checkpoint: <id>` trailer (when amendment accepted/forced).
+- Session metadata is written to `entire/checkpoints/v1`.
+
+### Scenario 2: Attach adds session to existing checkpoint
+
+Setup:
+1. Ensure latest commit already has `Entire-Checkpoint` trailer.
+2. Ensure a second transcript/session exists to attach.
+
+Run:
+1. Execute `entire attach <session-id> --agent <agent-name>`.
+
+Checks:
+
+```bash
+# Capture checkpoint ID from latest commit
+git log -1 --pretty=%B
+# Inspect checkpoint files on v1 branch for multiple session folders
+checkpoint_id="<id-from-commit-trailer>"
+shard_path="$(scripts/checkpoint-shard-path "$checkpoint_id")"
+git ls-tree --name-only entire/checkpoints/v1 "$shard_path"
+```
+
+Expected:
+- Attach reports that it added to existing checkpoint.
+- Checkpoint now contains additional session data.
+
+### Scenario 3: Session already attached
+
+Setup:
+1. Use a session ID that already has `LastCheckpointID` in session state.
+
+Run:
+1. Execute `entire attach <existing-session-id> --agent <agent-name>`.
+
+Expected:
+- Command reports session already has checkpoint.
+- Command offers to amend latest commit with existing checkpoint trailer.
+
+### Pass checklist
+
+- [ ] New-checkpoint attach flow validated.
+- [ ] Existing-checkpoint attach flow validated.
+- [ ] Already-attached flow validated.
+
+---
+
+## 7) `entire status` (regression guard)
 
 - What it does: reports current session status/phase information.
 - Use it for: quick health checks independent of committed checkpoint refs.
@@ -645,7 +719,7 @@ Expected:
 
 ---
 
-## 7) `entire rewind` (regression guard)
+## 8) `entire rewind` (regression guard)
 
 - What it does: restores repository files/logs to a prior checkpoint.
 - Use it for: undoing recent changes and returning to earlier state.
@@ -678,7 +752,7 @@ Capture:
 ## Exit Criteria
 
 Migration manual validation is complete when:
-- `resume`, `explain`, `doctor`, `clean`, and `migrate` pass applicable scenarios
+- `resume`, `explain`, `doctor`, `clean`, `migrate`, and `attach` pass applicable scenarios
 - remote fetch and `checkpoint_remote` paths pass in missing-local situations
 - rotation and cleanup lifecycle pass without violating `/main` permanence
 - `status` and `rewind` show no regressions

From f0b7d779421ba28210461ea82a901d79cc8a1d5d Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Fri, 3 Apr 2026 13:21:09 -0700
Subject: [PATCH 07/17] review: create scripts directory before helper script

Entire-Checkpoint: 6b60ad4c5992
---
 docs/guides/checkpoints-v2-manual-test-plan.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 502443fe05..97f345012d 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -79,6 +79,9 @@ Use this helper to derive `<shard_path>` from a checkpoint ID.
 Use the reusable executable script to determine the shard path.
 
 ```bash
+# Ensure helper directory exists
+mkdir -p scripts
+
 cat > scripts/checkpoint-shard-path <<'EOF'
 #!/usr/bin/env bash
 set -euo pipefail

From 05f4f270f5794e5bce50151d1efc802e30609be8 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Fri, 3 Apr 2026 16:35:09 -0700
Subject: [PATCH 08/17] review: add v2 attach validation scenario

Entire-Checkpoint: 72379f04c132
---
 .../guides/checkpoints-v2-manual-test-plan.md | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 97f345012d..42e307ff07 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -672,11 +672,43 @@ Expected:
 - Command reports session already has checkpoint.
 - Command offers to amend latest commit with existing checkpoint trailer.
 
+### Scenario 4: Attached session appears correctly in v2 refs
+
+Setup:
+1. Enable v2 mode in test settings (`checkpoints_v2=true`).
+2. Start from a commit with an `Entire-Checkpoint` trailer.
+3. Attach a new session to that checkpoint.
+
+Run:
+1. Execute `entire attach <session-id> --agent <agent-name>`.
+
+Checks:
+
+```bash
+# Read checkpoint ID from latest commit trailer
+git log -1 --pretty=%B
+# Set checkpoint id manually from trailer output
+checkpoint_id="<id-from-commit-trailer>"
+shard_path="$(scripts/checkpoint-shard-path "$checkpoint_id")"
+
+# Validate checkpoint metadata/session content on v2 main
+git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path"
+git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
+
+# Validate resumable transcript artifacts on v2 full/current
+git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path"
+```
+
+Expected:
+- Attached session is represented in v2 checkpoint metadata.
+- Required transcript artifacts are present in v2 refs for follow-up commands (`resume`/`explain`).
+
 ### Pass checklist
 
 - [ ] New-checkpoint attach flow validated.
 - [ ] Existing-checkpoint attach flow validated.
 - [ ] Already-attached flow validated.
+- [ ] v2 ref representation for attached sessions validated.
 
 ---
 

From fc1f7943b32b31f5a7f4f26a296a2604c2256a66 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Fri, 3 Apr 2026 16:37:19 -0700
Subject: [PATCH 09/17] review: remove out-of-scope status validation section

Entire-Checkpoint: 4b9a7556e812
---
 .../guides/checkpoints-v2-manual-test-plan.md | 46 +------------------
 1 file changed, 2 insertions(+), 44 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 42e307ff07..74bc2e887c 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -712,49 +712,7 @@ Expected:
 
 ---
 
-## 7) `entire status` (regression guard)
-
-- What it does: reports current session status/phase information.
-- Use it for: quick health checks independent of committed checkpoint refs.
-
-### Scenario 1: Baseline status behavior
-
-Setup:
-1. In `repo-a`, run normal session flow and create at least one checkpoint.
-
-Run:
-1. Execute `entire status`.
-
-Expected:
-- Status output reflects current session/phase accurately.
-
-### Scenario 2: Status with missing local v2 refs
-
-Setup:
-1. In disposable clone, remove local v2 refs.
-
-```bash
-git update-ref -d refs/entire/checkpoints/v2/main
-git update-ref -d refs/entire/checkpoints/v2/full/current
-for ref in $(git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/[0-9]*'); do
-  git update-ref -d "$ref"
-done
-```
-
-Run:
-1. Execute `entire status`.
-
-Expected:
-- Status remains functional and does not depend on committed v2 refs.
-
-### Pass checklist
-
-- [ ] Status remains correct before/after v2 writes.
-- [ ] Status remains functional when local v2 refs are absent.
-
----
-
-## 8) `entire rewind` (regression guard)
+## 7) `entire rewind` (regression guard)
 
 - What it does: restores repository files/logs to a prior checkpoint.
 - Use it for: undoing recent changes and returning to earlier state.
@@ -790,4 +748,4 @@ Migration manual validation is complete when:
 - `resume`, `explain`, `doctor`, `clean`, `migrate`, and `attach` pass applicable scenarios
 - remote fetch and `checkpoint_remote` paths pass in missing-local situations
 - rotation and cleanup lifecycle pass without violating `/main` permanence
-- `status` and `rewind` show no regressions
+- `rewind` shows no regressions

From 9965d9c70301df26bf8a0b4bdd578cb07de06db0 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Fri, 3 Apr 2026 16:44:02 -0700
Subject: [PATCH 10/17] review: simplify attach examples to default agent

Entire-Checkpoint: 4bd79b175323
---
 docs/guides/checkpoints-v2-manual-test-plan.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 74bc2e887c..1f708ffb14 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -619,7 +619,7 @@ Setup:
 3. Ensure latest commit does not already contain `Entire-Checkpoint` trailer.
 
 Run:
-1. Execute `entire attach <session-id> --agent <agent-name>`.
+1. Execute `entire attach <session-id>`.
 2. When prompted, allow trailer amendment (or rerun with `--force`).
 
 Checks:
@@ -643,7 +643,7 @@ Setup:
 2. Ensure a second transcript/session exists to attach.
 
 Run:
-1. Execute `entire attach <session-id> --agent <agent-name>`.
+1. Execute `entire attach <session-id>`.
 
 Checks:
 
@@ -666,7 +666,7 @@ Setup:
 1. Use a session ID that already has `LastCheckpointID` in session state.
 
 Run:
-1. Execute `entire attach <existing-session-id> --agent <agent-name>`.
+1. Execute `entire attach <existing-session-id>`.
 
 Expected:
 - Command reports session already has checkpoint.
@@ -680,7 +680,7 @@ Setup:
 3. Attach a new session to that checkpoint.
 
 Run:
-1. Execute `entire attach <session-id> --agent <agent-name>`.
+1. Execute `entire attach <session-id>`.
 
 Checks:
 

From cfb6022229910b3a66ab3182d3341d11359ceec2 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Fri, 3 Apr 2026 16:47:09 -0700
Subject: [PATCH 11/17] review: clarify trailer reuse in attach scenario

Entire-Checkpoint: 52a39b0356eb
---
 docs/guides/checkpoints-v2-manual-test-plan.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 1f708ffb14..005320fbff 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -639,7 +639,7 @@ Expected:
 ### Scenario 2: Attach adds session to existing checkpoint
 
 Setup:
-1. Ensure latest commit already has `Entire-Checkpoint` trailer.
+1. Ensure latest commit already has `Entire-Checkpoint` trailer (this reuses that checkpoint; it does not block attaching additional sessions).
 2. Ensure a second transcript/session exists to attach.
 
 Run:

From 0441abdfe9a66b74a6b6635a6e662056cf2860d3 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Fri, 3 Apr 2026 16:52:55 -0700
Subject: [PATCH 12/17] docs: clarify v2 support status and focus manual
 scenarios

Entire-Checkpoint: 844f7a5f83cd
---
 .../guides/checkpoints-v2-manual-test-plan.md | 167 +++---------------
 1 file changed, 22 insertions(+), 145 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 005320fbff..692cf7ad05 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -17,6 +17,15 @@ Goals:
 - Archived raw generations: `refs/entire/checkpoints/v2/full/<generation>`
 - v1 fallback remains available until v1 removal
 
+## Current v2 command support status
+
+To reduce confusion during rollout:
+- `entire resume`: supported now for checkpoints v2 read-path validation.
+- `entire explain`: v2 behavior is not fully supported yet; this command will be updated soon.
+- `entire attach`: v2 representation checks are forward-looking; full v2 behavior will be updated soon.
+- `entire migrate`: command not implemented yet; validation is deferred until it lands.
+- `entire doctor`, `entire clean`, `entire rewind`: included as practical sanity/regression checks, not deep v2 feature validation.
+
 ## Global Test Setup
 
 ### Test topology
@@ -186,7 +195,7 @@ git fetch origin refs/entire/checkpoints/v2/full/current:refs/entire/checkpoints
 
 ## Command Test Plan
 
-This guide is intentionally command-first. Each command section below includes self-contained setup, execution, checks, and expected outcomes.
+This guide is intentionally command-first and focused on common, high-signal manual scenarios. Rare edge cases and corruption cases belong in automated tests.
 
 ---
 
@@ -222,19 +231,7 @@ Expected:
 - Session restored and resume command printed.
 - Checkpoint data resolves from v2 (`/full/current`).
 
-### Scenario 2: Resume from archived generation
-
-Setup:
-1. In `repo-a`, generate enough checkpoints to rotate `/full/current`.
-2. Identify a checkpoint from before rotation.
-
-Run:
-1. Execute `entire resume <branch-containing-older-checkpoint>`.
-
-Expected:
-- Resume succeeds using raw transcript from an archived `refs/entire/checkpoints/v2/full/<generation>` ref.
-
-### Scenario 3: Local missing, remote present
+### Scenario 2: Local missing, remote present
 
 Setup:
 1. Use `repo-fresh` clone (preferred), or delete local v2 refs in disposable clone.
@@ -255,19 +252,7 @@ Run:
 Expected:
 - Resume fetches required data and succeeds when remote data exists.
 
-### Scenario 4: `checkpoint_remote` source
-
-Setup:
-1. Configure `checkpoint_remote`.
-2. Ensure v2 refs exist on checkpoint remote and not on origin.
-
-Run:
-1. Execute `entire resume <feature-branch>`.
-
-Expected:
-- Resume succeeds by fetching metadata/transcripts from checkpoint remote.
-
-### Scenario 5: v1 fallback
+### Scenario 3: v1 fallback
 
 Setup:
 1. Create checkpoint with `checkpoints_v2=false`.
@@ -282,9 +267,7 @@ Expected:
 ### Pass checklist
 
 - [ ] Baseline v2 resume validated.
-- [ ] Archived-generation lookup validated.
 - [ ] Missing-local fetch validated.
-- [ ] `checkpoint_remote` path validated.
 - [ ] v1 fallback validated.
 
 ---
@@ -294,29 +277,9 @@ Expected:
 - What it does: reads checkpoint transcript data and explains context.
 - Use it for: understanding what changed and why at a checkpoint.
 
-### Scenario 1: Compact transcript on `/main`
+Note: full checkpoints v2 behavior for `entire explain` is not implemented yet. This section is a short forward-looking validation target for upcoming updates.
 
-Setup:
-1. Create a checkpoint where compact transcript exists on `/main`.
-
-Run:
-1. Execute `entire explain <checkpoint-id-or-target>`.
-
-Checks:
-
-```bash
-# Read compact transcript (when available)
-git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
-# Read raw transcript
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
-# Read raw transcript from v1 fallback
-git show "entire/checkpoints/v1:${shard_path}/0/full.jsonl"
-```
-
-Expected:
-- Explain uses `transcript.jsonl` from `/main`.
-
-### Scenario 2: Fallback to raw transcript
+### Scenario 1: Preferred compact transcript path (future behavior)
 
 Setup:
 1. Create or identify a checkpoint where compact transcript is intentionally unavailable.
@@ -336,18 +299,7 @@ Run:
 Expected:
 - Explain falls back to raw transcript in `/full/*`.
 
-### Scenario 3: Local missing / remote present
-
-Setup:
-1. Remove local v2 refs in disposable clone or use `repo-fresh`.
-
-Run:
-1. Execute `entire explain <target>`.
-
-Expected:
-- Explain succeeds after fetching from remote.
-
-### Scenario 4: v1 fallback
+### Scenario 2: v1 fallback (current compatibility)
 
 Setup:
 1. Use branch/checkpoint where data exists only in v1.
@@ -360,8 +312,7 @@ Expected:
 
 ### Pass checklist
 
-- [ ] Compact transcript preferred when present.
-- [ ] Raw fallback validated.
+- [ ] Future compact-transcript path documented and validated when shipped.
 - [ ] v1 fallback validated.
 
 ---
@@ -418,25 +369,10 @@ Expected:
 - Doctor detects stuck sessions and applies selected remediation.
 - After condense/discard, corresponding session state/shadow-branch data is reduced or removed.
 
-### Scenario 3: Disconnected metadata branch repair
-
-Setup:
-1. Create local/remote `entire/checkpoints/v1` branches with no common ancestor (use disposable repo).
-
-Run:
-1. Execute `entire doctor`.
-2. Approve metadata repair when prompted (or run with `--force`).
-
-Expected:
-- Doctor detects disconnected metadata branch state.
-- Doctor repairs by reconciling local checkpoints onto remote tip.
-- Local and remote metadata branches become connected.
-
 ### Pass checklist
 
 - [ ] No-issue case reports clean status.
 - [ ] Stuck-session detection and remediation validated.
-- [ ] Disconnected metadata-branch repair validated.
 
 ---
 
@@ -483,47 +419,22 @@ Expected:
 ### Scenario 3: Repository-wide orphan cleanup (`--all`)
 
 Setup:
-1. Create orphaned data (e.g., old shadow branches, orphaned session-state files, or orphaned checkpoint entries on `entire/checkpoints/v1`).
+1. Create orphaned data (for example: old shadow branches or orphaned session-state files).
 
 Run:
 1. Execute `entire clean --all --dry-run`.
 2. Execute `entire clean --all`.
 
-Checks:
-
-```bash
-# List shadow branches before/after --all
-git branch --list 'entire/*'
-# Inspect session state files before/after --all
-ls .git/entire-sessions
-# Inspect metadata branch tip commit before/after --all
-git log --oneline -1 entire/checkpoints/v1
-```
-
 Expected:
 - Dry-run previews orphaned items.
 - `--all` removes orphaned items and temporary files.
 - `entire/checkpoints/v1` branch is preserved.
 
-### Scenario 4: Single-session cleanup (`--session`)
-
-Setup:
-1. Ensure at least one known session ID exists.
-
-Run:
-1. Execute `entire clean --session <session-id> --dry-run`.
-2. Execute `entire clean --session <session-id>`.
-
-Expected:
-- Only the specified session is cleaned.
-- File changes remain in working directory (metadata/session cleanup only).
-
 ### Pass checklist
 
 - [ ] Current-HEAD cleanup behavior validated.
 - [ ] Active-session guard and `--force` behavior validated.
 - [ ] `--all` orphan cleanup behavior validated.
-- [ ] `--session` cleanup behavior validated.
 
 ---
 
@@ -576,33 +487,10 @@ git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
 Expected:
 - v1 checkpoints are migrated to v2 split refs.
 
-### Scenario 2: Idempotency
-
-Setup:
-1. Keep repository unchanged after first migrate run.
-
-Run:
-1. Execute `entire migrate` again.
-
-Expected:
-- No duplicate logical checkpoint entries.
-
-### Scenario 3: Non-compaction path
-
-Setup:
-1. Use checkpoint data where compaction is unavailable.
-
-Run:
-1. Execute `entire migrate`.
-
-Expected:
-- `/main` has metadata/prompt (and no compact transcript), `/full/*` has raw transcript.
-
 ### Pass checklist
 
 - [ ] Migration output correctness validated.
-- [ ] Idempotency validated.
-- [ ] Task metadata continuity validated.
+- [ ] Idempotency and non-compaction checks moved to automated tests.
 
 ---
 
@@ -611,6 +499,8 @@ Expected:
 - What it does: attaches an existing agent transcript/session to checkpoint metadata when hooks did not capture it.
 - Use it for: recovering missed checkpoints or linking research sessions to the latest commit.
 
+Note: full checkpoints v2 behavior for `entire attach` is still in progress and will be updated soon.
+
 ### Scenario 1: Attach creates a new checkpoint and trailer
 
 Setup:
@@ -660,19 +550,7 @@ Expected:
 - Attach reports that it added to existing checkpoint.
 - Checkpoint now contains additional session data.
 
-### Scenario 3: Session already attached
-
-Setup:
-1. Use a session ID that already has `LastCheckpointID` in session state.
-
-Run:
-1. Execute `entire attach <existing-session-id>`.
-
-Expected:
-- Command reports session already has checkpoint.
-- Command offers to amend latest commit with existing checkpoint trailer.
-
-### Scenario 4: Attached session appears correctly in v2 refs
+### Scenario 3: Attached session appears correctly in v2 refs (future behavior)
 
 Setup:
 1. Enable v2 mode in test settings (`checkpoints_v2=true`).
@@ -707,7 +585,6 @@ Expected:
 
 - [ ] New-checkpoint attach flow validated.
 - [ ] Existing-checkpoint attach flow validated.
-- [ ] Already-attached flow validated.
 - [ ] v2 ref representation for attached sessions validated.
 
 ---
@@ -747,5 +624,5 @@ Capture:
 Migration manual validation is complete when:
 - `resume`, `explain`, `doctor`, `clean`, `migrate`, and `attach` pass applicable scenarios
 - remote fetch and `checkpoint_remote` paths pass in missing-local situations
-- rotation and cleanup lifecycle pass without violating `/main` permanence
+- expanded edge-case/corruption checks remain covered by automated tests
 - `rewind` shows no regressions

From cb64327a0a93843109bf3f5252ae947c4ea68433 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Mon, 6 Apr 2026 15:16:50 -0700
Subject: [PATCH 13/17] docs: tighten v2 test guide wording and rollout gates

Entire-Checkpoint: 1e7a94604fc7
---
 .../guides/checkpoints-v2-manual-test-plan.md | 66 ++++++++++---------
 1 file changed, 36 insertions(+), 30 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 692cf7ad05..79e10fb23b 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -7,7 +7,7 @@ This is the command-first manual QA plan for the checkpoints v2 migration. It is
 Goals:
 - Validate v2 split-ref read/write behavior.
 - Validate local-missing/remote-present fetch behavior.
-- Validate rotation, cleanup, and migration lifecycle behavior.
+- Validate core cleanup and migration-readiness flows (with edge/corruption lifecycle cases covered by automated tests).
 - Provide copy-paste test steps and evidence collection.
 
 ## v2 Invariants
@@ -21,7 +21,7 @@ Goals:
 
 To reduce confusion during rollout:
 - `entire resume`: supported now for checkpoints v2 read-path validation.
-- `entire explain`: v2 behavior is not fully supported yet; this command will be updated soon.
+- `entire explain`: supported for compact transcript path validation.
 - `entire attach`: v2 representation checks are forward-looking; full v2 behavior will be updated soon.
 - `entire migrate`: command not implemented yet; validation is deferred until it lands.
 - `entire doctor`, `entire clean`, `entire rewind`: included as practical sanity/regression checks, not deep v2 feature validation.
@@ -51,6 +51,8 @@ Set strategy options in `.entire/settings.json`:
 }
 ```
 
+Note: some strategy option keys are rollout-dependent and may become effective as command support lands.
+
 ### Baseline checks (run before each command section)
 
 ```bash
@@ -204,7 +206,7 @@ This guide is intentionally command-first and focused on common, high-signal man
 - What it does: restores the session transcript and prints the resume command.
 - Use it for: continuing work from a checkpointed branch/session.
 
-### Scenario 1: Baseline v2 resume
+### Scenario 1: Baseline v2 resume (Core)
 
 Setup:
 1. In `repo-a`, enable `checkpoints_v2=true` and `push_v2_refs=true`.
@@ -231,7 +233,7 @@ Expected:
 - Session restored and resume command printed.
 - Checkpoint data resolves from v2 (`/full/current`).
 
-### Scenario 2: Local missing, remote present
+### Scenario 2: Local missing, remote present (Core)
 
 Setup:
 1. Use `repo-fresh` clone (preferred), or delete local v2 refs in disposable clone.
@@ -252,7 +254,7 @@ Run:
 Expected:
 - Resume fetches required data and succeeds when remote data exists.
 
-### Scenario 3: v1 fallback
+### Scenario 3: v1 fallback (Optional)
 
 Setup:
 1. Create checkpoint with `checkpoints_v2=false`.
@@ -277,29 +279,25 @@ Expected:
 - What it does: reads checkpoint transcript data and explains context.
 - Use it for: understanding what changed and why at a checkpoint.
 
-Note: full checkpoints v2 behavior for `entire explain` is not implemented yet. This section is a short forward-looking validation target for upcoming updates.
+Note: compact transcript behavior is supported for `entire explain`; broader v2 behavior continues to evolve.
 
-### Scenario 1: Preferred compact transcript path (future behavior)
+### Scenario 1: Compact transcript path (Core)
 
 Setup:
-1. Create or identify a checkpoint where compact transcript is intentionally unavailable.
-2. Recommended setup path:
-   - Use an external agent/plugin that does **not** advertise `compact_transcript` capability.
-   - Create one checkpoint with `checkpoints_v2=true`.
-3. Verify setup before running explain:
+1. Create or identify a checkpoint where compact transcript exists on v2 `/main`.
+2. Verify setup before running explain:
 
 ```bash
 git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
 ```
 
 Run:
 1. Execute `entire explain <checkpoint-id-or-target>`.
 
 Expected:
-- Explain falls back to raw transcript in `/full/*`.
+- Explain uses compact transcript from v2 `/main`.
 
-### Scenario 2: v1 fallback (current compatibility)
+### Scenario 2: v1 fallback (current compatibility, Optional)
 
 Setup:
 1. Use branch/checkpoint where data exists only in v1.
@@ -312,7 +310,7 @@ Expected:
 
 ### Pass checklist
 
-- [ ] Future compact-transcript path documented and validated when shipped.
+- [ ] Compact transcript path validated.
 - [ ] v1 fallback validated.
 
 ---
@@ -322,7 +320,7 @@ Expected:
 - What it does: diagnoses and fixes disconnected `entire/checkpoints/v1` metadata branches and stuck sessions.
 - Use it for: recovering from session-state/shadow-branch issues and metadata-branch divergence.
 
-### Scenario 1: No issues detected
+### Scenario 1: No issues detected (Core)
 
 Setup:
 1. Ensure no stale sessions are stuck in `ACTIVE` for >1h.
@@ -348,7 +346,7 @@ git ls-remote origin refs/heads/entire/checkpoints/v1
 Expected:
 - Doctor reports no disconnected metadata issue and no stuck sessions.
 
-### Scenario 2: Stuck session handling
+### Scenario 2: Stuck session handling (Optional)
 
 Setup:
 1. Create a session in `ACTIVE` and make it stale (or create an `ENDED` session with uncondensed data).
@@ -381,7 +379,7 @@ Expected:
 - What it does: cleans session state and shadow branch data for current HEAD, or orphaned Entire data with `--all`.
 - Use it for: removing stale session metadata and orphaned Entire artifacts.
 
-### Scenario 1: Current HEAD cleanup
+### Scenario 1: Current HEAD cleanup (Core)
 
 Setup:
 1. In `repo-a`, create a session on the current HEAD so there is session state and shadow-branch data.
@@ -403,7 +401,7 @@ Expected:
 - `--dry-run` lists items without deleting.
 - `entire clean` removes current-HEAD session state and shadow branch data.
 
-### Scenario 2: Active-session guard and `--force`
+### Scenario 2: Active-session guard and `--force` (Optional)
 
 Setup:
 1. Start an active session on current HEAD.
@@ -416,7 +414,7 @@ Expected:
 - Without `--force`, command warns and refuses to clean active session data.
 - With `--force`, command proceeds.
 
-### Scenario 3: Repository-wide orphan cleanup (`--all`)
+### Scenario 3: Repository-wide orphan cleanup (`--all`, Optional)
 
 Setup:
 1. Create orphaned data (for example: old shadow branches or orphaned session-state files).
@@ -445,7 +443,7 @@ Expected:
 
 Note: `entire migrate` is not implemented yet. Treat this section as a forward-looking validation plan and run it only after the command becomes available.
 
-### Scenario 1: First migration run
+### Scenario 1: First migration run (Core, when command is available)
 
 Setup:
 1. Prepare repository with v1-only checkpoint history.
@@ -501,7 +499,7 @@ Expected:
 
 Note: full checkpoints v2 behavior for `entire attach` is still in progress and will be updated soon.
 
-### Scenario 1: Attach creates a new checkpoint and trailer
+### Scenario 1: Attach creates a new checkpoint and trailer (Core)
 
 Setup:
 1. Ensure repository has at least one commit.
@@ -526,7 +524,7 @@ Expected:
 - Latest commit includes `Entire-Checkpoint: <id>` trailer (when amendment accepted/forced).
 - Session metadata is written to `entire/checkpoints/v1`.
 
-### Scenario 2: Attach adds session to existing checkpoint
+### Scenario 2: Attach adds session to existing checkpoint (Optional)
 
 Setup:
 1. Ensure latest commit already has `Entire-Checkpoint` trailer (this reuses that checkpoint; it does not block attaching additional sessions).
@@ -550,7 +548,7 @@ Expected:
 - Attach reports that it added to existing checkpoint.
 - Checkpoint now contains additional session data.
 
-### Scenario 3: Attached session appears correctly in v2 refs (future behavior)
+### Scenario 3: Attached session appears correctly in v2 refs (future behavior, Optional)
 
 Setup:
 1. Enable v2 mode in test settings (`checkpoints_v2=true`).
@@ -594,7 +592,7 @@ Expected:
 - What it does: restores repository files/logs to a prior checkpoint.
 - Use it for: undoing recent changes and returning to earlier state.
 
-### Scenario 1: Rewind normal flow
+### Scenario 1: Rewind normal flow (Core)
 
 Setup:
 1. Create at least two temporary checkpoints in one session.
@@ -621,8 +619,16 @@ Capture:
 
 ## Exit Criteria
 
-Migration manual validation is complete when:
-- `resume`, `explain`, `doctor`, `clean`, `migrate`, and `attach` pass applicable scenarios
-- remote fetch and `checkpoint_remote` paths pass in missing-local situations
+### Current rollout gate
+
+Current manual validation is complete when:
+- `resume`, `doctor`, `clean`, and `rewind` pass applicable scenarios
+- `explain` compact transcript scenario passes
+- remote fetch paths pass in missing-local situations
+
+### Future rollout gate
+
+Future manual validation is complete when:
+- `attach` v2 representation scenario passes with fully shipped v2 behavior
+- `migrate` scenario passes after the command is implemented
 - expanded edge-case/corruption checks remain covered by automated tests
-- `rewind` shows no regressions

From e6e7a841379ad6ad1088cb84d890d69a9f7640c9 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Tue, 21 Apr 2026 15:34:23 -0700
Subject: [PATCH 14/17] docs: refresh checkpoints v2 manual test plan overview

Entire-Checkpoint: c7bf696d9b1a
---
 .../guides/checkpoints-v2-manual-test-plan.md | 64 +++++++++++++------
 1 file changed, 44 insertions(+), 20 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 79e10fb23b..d0167ab9eb 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -2,29 +2,33 @@
 
 ## Purpose
 
-This is the command-first manual QA plan for the checkpoints v2 migration. It is intended to be used throughout rollout without needing rewrites as additional command support lands.
+This is the command-first manual QA plan for the current checkpoints v2 implementation.
 
 Goals:
-- Validate v2 split-ref read/write behavior.
+- Validate current v2 split-ref write and read behavior.
 - Validate local-missing/remote-present fetch behavior.
-- Validate core cleanup and migration-readiness flows (with edge/corruption lifecycle cases covered by automated tests).
+- Validate cleanup, doctor, attach, and migration flows that now exist in the CLI.
 - Provide copy-paste test steps and evidence collection.
 
 ## v2 Invariants
 
-- Permanent metadata + compact transcripts: `refs/entire/checkpoints/v2/main`
-- Raw resumable logs: `refs/entire/checkpoints/v2/full/current`
-- Archived raw generations: `refs/entire/checkpoints/v2/full/<generation>`
-- v1 fallback remains available until v1 removal
+- Permanent metadata + compact transcripts live at `refs/entire/checkpoints/v2/main`
+- Active raw resumable transcripts live at `refs/entire/checkpoints/v2/full/current`
+- Archived raw transcript generations live at `refs/entire/checkpoints/v2/full/<generation>`
+- v1 compatibility still exists for fallback and migration scenarios unless running `checkpoints_version: 2`
+- v2 path layout differs by ref:
+  - `/main` contains `metadata.json`, session `metadata.json`, `prompt.txt`, `transcript.jsonl`, `transcript_hash.txt`
+  - `/full/current` contains `raw_transcript` and `raw_transcript_hash.txt`
 
 ## Current v2 command support status
 
-To reduce confusion during rollout:
-- `entire resume`: supported now for checkpoints v2 read-path validation.
-- `entire explain`: supported for compact transcript path validation.
-- `entire attach`: v2 representation checks are forward-looking; full v2 behavior will be updated soon.
-- `entire migrate`: command not implemented yet; validation is deferred until it lands.
-- `entire doctor`, `entire clean`, `entire rewind`: included as practical sanity/regression checks, not deep v2 feature validation.
+- `entire resume`: supports v2 reads and v1 fallback.
+- `entire explain`: supports v2 reads, compact transcript reads from `/main`, fetch-on-miss, and v1 fallback.
+- `entire attach`: writes v2 when checkpoints v2 is enabled, while still supporting v1 when not.
+- `entire migrate --checkpoints v2`: implemented and hidden; migrates v1 committed checkpoints into v2.
+- `entire doctor`: includes v2-specific health checks in addition to the legacy metadata-branch/session checks.
+- `entire clean`: includes v2 archived-generation cleanup in addition to session/shadow cleanup.
+- `entire rewind`: included mainly as a regression guard; it is not a primary v2 storage validation command.
 
 ## Global Test Setup
 
@@ -46,12 +50,30 @@ Set strategy options in `.entire/settings.json`:
   "strategy_options": {
     "checkpoints_v2": true,
     "push_v2_refs": true,
-    "generation_retention_days": 14
+    "full_transcript_generation_retention_days": 14
   }
 }
 ```
 
-Note: some strategy option keys are rollout-dependent and may become effective as command support lands.
+Notes:
+- `checkpoints_v2: true` enables dual-write/read behavior.
+- `push_v2_refs: true` pushes `refs/entire/checkpoints/v2/main` and `refs/entire/checkpoints/v2/full/current`.
+- `full_transcript_generation_retention_days` controls cleanup of archived `/full/<generation>` refs.
+- `checkpoints_version: 2` is also supported and is the stricter v2-only mode:
+
+```json
+{
+  "strategy_options": {
+    "checkpoints_version": 2,
+    "full_transcript_generation_retention_days": 14
+  }
+}
+```
+
+In `checkpoints_version: 2` mode:
+- v2 is always enabled
+- v2 refs are always pushed
+- new writes should skip v1
 
 ### Baseline checks (run before each command section)
 
@@ -124,12 +146,14 @@ git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path"
 git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path"
 # Read checkpoint summary metadata
 git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
-# Read compact transcript (when available)
+# Read compact transcript from /main
 git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
-# Read raw transcript
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
-# Read raw transcript content hash
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/content_hash.txt"
+# Read compact transcript hash from /main
+git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript_hash.txt"
+# Read raw transcript from /full/current
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/raw_transcript"
+# Read raw transcript hash from /full/current
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/raw_transcript_hash.txt"
 ```
 
 ### Archived generation checks

From 52c066bb84309bd1d66fdb78363155b08ee6b4cc Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Tue, 21 Apr 2026 15:54:31 -0700
Subject: [PATCH 15/17] docs: narrow manual checkpoint test scenarios

Entire-Checkpoint: f8dba798c948
---
 .../guides/checkpoints-v2-manual-test-plan.md | 55 +++++++++++++++++--
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index d0167ab9eb..e7da67d09a 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -255,7 +255,9 @@ git ls-remote origin 'refs/entire/checkpoints/v2/*'
 
 Expected:
 - Session restored and resume command printed.
-- Checkpoint data resolves from v2 (`/full/current`).
+- Checkpoint data resolves from v2:
+  - metadata from `refs/entire/checkpoints/v2/main`
+  - transcript content from `refs/entire/checkpoints/v2/full/current`
 
 ### Scenario 2: Local missing, remote present (Core)
 
@@ -276,7 +278,8 @@ Run:
 1. Execute `entire resume <feature-branch>`.
 
 Expected:
-- Resume fetches required data and succeeds when remote data exists.
+- Resume fetches the required v2 refs from remote and succeeds when remote data exists.
+- Resume should not require pre-existing local `refs/entire/checkpoints/v2/*` refs.
 
 ### Scenario 3: v1 fallback (Optional)
 
@@ -303,7 +306,11 @@ Expected:
 - What it does: reads checkpoint transcript data and explains context.
 - Use it for: understanding what changed and why at a checkpoint.
 
-Note: compact transcript behavior is supported for `entire explain`; broader v2 behavior continues to evolve.
+Current v2 behavior to validate manually:
+- explain prefers v2 checkpoint data when both v1 and v2 exist
+- default explain can use compact transcript data from `/main`
+- explain can fetch missing checkpoint refs from remote
+- explain still falls back to v1 when the checkpoint exists only in v1
 
 ### Scenario 1: Compact transcript path (Core)
 
@@ -320,8 +327,23 @@ Run:
 
 Expected:
 - Explain uses compact transcript from v2 `/main`.
+- Intent/prompt text should reflect the compact transcript content, not v1 fallback content.
 
-### Scenario 2: v1 fallback (current compatibility, Optional)
+### Scenario 2: Prefer v2 over v1 when dual-write data exists (Core)
+
+Setup:
+1. Create a dual-write checkpoint with `checkpoints_v2=true`.
+2. Confirm the checkpoint exists on both v1 and v2.
+3. If you want to make preference obvious, temporarily alter only the v1 transcript for that checkpoint in a disposable clone so the prompt text differs from the v2 compact transcript.
+
+Run:
+1. Execute `entire explain <checkpoint-id-or-target>`.
+
+Expected:
+- Explain prefers v2 checkpoint data instead of v1 when both exist.
+- Output intent/prompt text matches the v2 compact transcript.
+
+### Scenario 3: v1 fallback when checkpoint exists only in v1 (Optional)
 
 Setup:
 1. Use branch/checkpoint where data exists only in v1.
@@ -332,10 +354,35 @@ Run:
 Expected:
 - Explain succeeds via v1 fallback.
 
+### Scenario 4: Fetch missing refs from remote (Core)
+
+Setup:
+1. Create a dual-write checkpoint with `checkpoints_v2=true` and `push_v2_refs=true`.
+2. Push checkpoint refs to `origin`.
+3. In a disposable clone, delete local v1 and v2 checkpoint refs.
+
+Run:
+1. Execute `entire explain --checkpoint <checkpoint-id>`.
+
+Expected:
+- Explain fetches missing checkpoint refs from remote and succeeds.
+- Output should contain the expected prompt/intent text from the checkpoint.
+
+### Automated coverage note
+
+The following are intentionally left to automated tests rather than this manual guide:
+- malformed or partially missing v2 refs
+- default explain behavior when `/full/current` is missing but `/main` still exists
+- v2-only listing after deleting v1 metadata
+- fetch-on-miss safety when local checkpoint refs are ahead of remote
+- corruption, race, and ref-reconciliation scenarios
+
 ### Pass checklist
 
 - [ ] Compact transcript path validated.
+- [ ] v2-preferred read path validated.
 - [ ] v1 fallback validated.
+- [ ] Remote fetch path validated.
 
 ---
 

From ba7ab0c006422c7b4069e4c2d0cac93c17712421 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Tue, 21 Apr 2026 16:12:54 -0700
Subject: [PATCH 16/17] docs: focus checkpoint manual plan on core workflows

Entire-Checkpoint: ff85358834f8
---
 .../guides/checkpoints-v2-manual-test-plan.md | 129 +++++++++++-------
 1 file changed, 80 insertions(+), 49 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index e7da67d09a..8e0b56bd0f 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -388,8 +388,8 @@ The following are intentionally left to automated tests rather than this manual
 
 ## 3) `entire doctor`
 
-- What it does: diagnoses and fixes disconnected `entire/checkpoints/v1` metadata branches and stuck sessions.
-- Use it for: recovering from session-state/shadow-branch issues and metadata-branch divergence.
+- What it does: diagnoses and fixes checkpoint/session issues, including v2-specific health checks.
+- Use it for: recovering from session-state/shadow-branch issues and spotting broken checkpoint metadata state.
 
 ### Scenario 1: No issues detected (Core)
 
@@ -415,9 +415,12 @@ git ls-remote origin refs/heads/entire/checkpoints/v1
 ```
 
 Expected:
-- Doctor reports no disconnected metadata issue and no stuck sessions.
+- Doctor reports a clean state for:
+  - legacy metadata connectivity
+  - v2 ref existence/count health when v2 is enabled
+  - stuck-session detection
 
-### Scenario 2: Stuck session handling (Optional)
+### Scenario 2: Stuck session handling (Core)
 
 Setup:
 1. Create a session in `ACTIVE` and make it stale (or create an `ENDED` session with uncondensed data).
@@ -438,6 +441,14 @@ Expected:
 - Doctor detects stuck sessions and applies selected remediation.
 - After condense/discard, corresponding session state/shadow-branch data is reduced or removed.
 
+### Automated coverage note
+
+The following are intentionally left to automated tests rather than this manual guide:
+- disconnected v2 `/main` repair paths
+- archived generation sequence/metadata edge cases
+- partial-ref inconsistencies and broken-object cases
+- metadata reconciliation and remote divergence corner cases
+
 ### Pass checklist
 
 - [ ] No-issue case reports clean status.
@@ -447,7 +458,7 @@ Expected:
 
 ## 4) `entire clean`
 
-- What it does: cleans session state and shadow branch data for current HEAD, or orphaned Entire data with `--all`.
+- What it does: cleans session state and shadow branch data for current HEAD, or repository-wide Entire artifacts with `--all`.
 - Use it for: removing stale session metadata and orphaned Entire artifacts.
 
 ### Scenario 1: Current HEAD cleanup (Core)
@@ -485,25 +496,31 @@ Expected:
 - Without `--force`, command warns and refuses to clean active session data.
 - With `--force`, command proceeds.
 
-### Scenario 3: Repository-wide orphan cleanup (`--all`, Optional)
+### Scenario 3: Repository-wide cleanup preview (`--all`, Optional)
 
 Setup:
-1. Create orphaned data (for example: old shadow branches or orphaned session-state files).
+1. Create repository-wide Entire data to clean (for example: old shadow branches, old session-state files, or archived v2 generations).
 
 Run:
 1. Execute `entire clean --all --dry-run`.
-2. Execute `entire clean --all`.
 
 Expected:
 - Dry-run previews orphaned items.
-- `--all` removes orphaned items and temporary files.
-- `entire/checkpoints/v1` branch is preserved.
+- Preview includes the kinds of items that would be removed.
+- Checkpoint metadata refs/branches are preserved.
+
+### Automated coverage note
+
+The following are intentionally left to automated tests rather than this manual guide:
+- archived generation retention edge cases
+- partial cleanup failures and recovery
+- low-level repository corruption scenarios
 
 ### Pass checklist
 
 - [ ] Current-HEAD cleanup behavior validated.
 - [ ] Active-session guard and `--force` behavior validated.
-- [ ] `--all` orphan cleanup behavior validated.
+- [ ] `--all` preview behavior validated.
 
 ---
 
@@ -512,15 +529,15 @@ Expected:
 - What it does: migrates v1 checkpoint storage into v2 split refs.
 - Use it for: upgrading repositories with existing v1 checkpoint history.
 
-Note: `entire migrate` is not implemented yet. Treat this section as a forward-looking validation plan and run it only after the command becomes available.
+Note: `entire migrate` is implemented as a hidden command. Run it explicitly as `entire migrate --checkpoints v2`.
 
-### Scenario 1: First migration run (Core, when command is available)
+### Scenario 1: First migration run (Core)
 
 Setup:
 1. Prepare repository with v1-only checkpoint history.
 
 Run:
-1. Execute `entire migrate`.
+1. Execute `entire migrate --checkpoints v2`.
 
 Checks:
 Run this block before migration:
@@ -550,16 +567,23 @@ git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
 # Read compact transcript (when available)
 git show "refs/entire/checkpoints/v2/main:${shard_path}/0/transcript.jsonl"
 # Read raw transcript
-git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/full.jsonl"
+git show "refs/entire/checkpoints/v2/full/current:${shard_path}/0/raw_transcript"
 ```
 
 Expected:
 - v1 checkpoints are migrated to v2 split refs.
 
+### Automated coverage note
+
+The following are intentionally left to automated tests rather than this manual guide:
+- idempotency and `--force` overwrite behavior
+- partial v2 repair/backfill cases
+- compact transcript generation failures
+- multi-session and task-metadata migration edge cases
+
 ### Pass checklist
 
 - [ ] Migration output correctness validated.
-- [ ] Idempotency and non-compaction checks moved to automated tests.
 
 ---
 
@@ -568,8 +592,6 @@ Expected:
 - What it does: attaches an existing agent transcript/session to checkpoint metadata when hooks did not capture it.
 - Use it for: recovering missed checkpoints or linking research sessions to the latest commit.
 
-Note: full checkpoints v2 behavior for `entire attach` is still in progress and will be updated soon.
-
 ### Scenario 1: Attach creates a new checkpoint and trailer (Core)
 
 Setup:
@@ -595,11 +617,13 @@ Expected:
 - Latest commit includes `Entire-Checkpoint: <id>` trailer (when amendment accepted/forced).
 - Session metadata is written to `entire/checkpoints/v1`.
 
-### Scenario 2: Attach adds session to existing checkpoint (Optional)
+### Scenario 2: Attach writes v2 artifacts when v2 is enabled (Core)
 
 Setup:
-1. Ensure latest commit already has `Entire-Checkpoint` trailer (this reuses that checkpoint; it does not block attaching additional sessions).
-2. Ensure a second transcript/session exists to attach.
+1. Enable v2 mode in test settings (`checkpoints_v2=true`).
+2. Ensure repository has at least one commit.
+3. Ensure target session transcript exists on disk for the selected agent.
+4. Ensure latest commit does not already contain `Entire-Checkpoint` trailer.
 
 Run:
 1. Execute `entire attach <session-id>`.
@@ -607,24 +631,28 @@ Run:
 Checks:
 
 ```bash
-# Capture checkpoint ID from latest commit
+# Read checkpoint ID from latest commit trailer
 git log -1 --pretty=%B
-# Inspect checkpoint files on v1 branch for multiple session folders
 checkpoint_id="<id-from-commit-trailer>"
 shard_path="$(scripts/checkpoint-shard-path "$checkpoint_id")"
-git ls-tree --name-only entire/checkpoints/v1 "$shard_path"
+
+# Validate checkpoint metadata/session content on v2 main
+git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path"
+git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
+
+# Validate transcript artifacts on v2 full/current
+git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path"
 ```
 
 Expected:
-- Attach reports that it added to existing checkpoint.
-- Checkpoint now contains additional session data.
+- Attach writes the checkpoint to v2 as well as the normal attach destination.
+- Required v2 metadata and transcript artifacts are present for follow-up commands such as `resume` and `explain`.
 
-### Scenario 3: Attached session appears correctly in v2 refs (future behavior, Optional)
+### Scenario 3: Attach adds session to existing checkpoint (Optional)
 
 Setup:
-1. Enable v2 mode in test settings (`checkpoints_v2=true`).
-2. Start from a commit with an `Entire-Checkpoint` trailer.
-3. Attach a new session to that checkpoint.
+1. Ensure latest commit already has `Entire-Checkpoint` trailer (this reuses that checkpoint; it does not block attaching additional sessions).
+2. Ensure a second transcript/session exists to attach.
 
 Run:
 1. Execute `entire attach <session-id>`.
@@ -632,29 +660,31 @@ Run:
 Checks:
 
 ```bash
-# Read checkpoint ID from latest commit trailer
+# Capture checkpoint ID from latest commit
 git log -1 --pretty=%B
-# Set checkpoint id manually from trailer output
+# Inspect checkpoint files on v1 branch for multiple session folders
 checkpoint_id="<id-from-commit-trailer>"
 shard_path="$(scripts/checkpoint-shard-path "$checkpoint_id")"
-
-# Validate checkpoint metadata/session content on v2 main
-git ls-tree --name-only refs/entire/checkpoints/v2/main "$shard_path"
-git show "refs/entire/checkpoints/v2/main:${shard_path}/metadata.json"
-
-# Validate resumable transcript artifacts on v2 full/current
-git ls-tree --name-only refs/entire/checkpoints/v2/full/current "$shard_path"
+git ls-tree --name-only entire/checkpoints/v1 "$shard_path"
 ```
 
 Expected:
-- Attached session is represented in v2 checkpoint metadata.
-- Required transcript artifacts are present in v2 refs for follow-up commands (`resume`/`explain`).
+- Attach reports that it added to existing checkpoint.
+- Checkpoint now contains additional session data.
+
+### Automated coverage note
+
+The following are intentionally left to automated tests rather than this manual guide:
+- agent-specific transcript discovery edge cases
+- token usage extraction details
+- existing-checkpoint merge edge cases across multiple sessions
+- attach failure/recovery paths
 
 ### Pass checklist
 
 - [ ] New-checkpoint attach flow validated.
+- [ ] v2 attach write path validated.
 - [ ] Existing-checkpoint attach flow validated.
-- [ ] v2 ref representation for attached sessions validated.
 
 ---
 
@@ -675,6 +705,10 @@ Run:
 Expected:
 - Files and prompt/log context restore to selected checkpoint state.
 
+### Automated coverage note
+
+The deeper rewind matrix belongs in automated tests. Manual validation here is only a smoke test to ensure the main rewind workflow still works after v2 changes.
+
 ### Pass checklist
 
 - [ ] Rewind still restores expected files and prompt context.
@@ -694,12 +728,9 @@ Capture:
 
 Current manual validation is complete when:
 - `resume`, `doctor`, `clean`, and `rewind` pass applicable scenarios
-- `explain` compact transcript scenario passes
+- `explain` core scenarios pass
+- `attach` core scenarios pass
+- `migrate` core scenario passes when v1 data exists to migrate
 - remote fetch paths pass in missing-local situations
 
-### Future rollout gate
-
-Future manual validation is complete when:
-- `attach` v2 representation scenario passes with fully shipped v2 behavior
-- `migrate` scenario passes after the command is implemented
-- expanded edge-case/corruption checks remain covered by automated tests
+Expanded edge-case and corruption coverage should remain in automated tests rather than this manual plan.

From d1e8b135f08e7bf1252de60871a86c5d08869420 Mon Sep 17 00:00:00 2001
From: Sven Pfleiderer <sven@entire.io>
Date: Tue, 21 Apr 2026 16:26:20 -0700
Subject: [PATCH 17/17] docs: polish checkpoint manual test plan wording

Entire-Checkpoint: 41c5b2f4a7ac
---
 docs/guides/checkpoints-v2-manual-test-plan.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/docs/guides/checkpoints-v2-manual-test-plan.md b/docs/guides/checkpoints-v2-manual-test-plan.md
index 8e0b56bd0f..e61b30c998 100644
--- a/docs/guides/checkpoints-v2-manual-test-plan.md
+++ b/docs/guides/checkpoints-v2-manual-test-plan.md
@@ -84,7 +84,7 @@ git show-ref --verify -- refs/entire/checkpoints/v2/main
 git show-ref --verify -- refs/entire/checkpoints/v2/full/current
 # List all local v2 raw refs (current + archived generations)
 git for-each-ref --format='%(refname)' 'refs/entire/checkpoints/v2/full/*'
-# Verify legacy v1 branch exists for fallback tests
+# Verify legacy v1 branch exists when running fallback or migration tests
 git show-ref --verify -- refs/heads/entire/checkpoints/v1
 ```
 
@@ -109,8 +109,6 @@ git ls-remote origin 'refs/entire/checkpoints/v2/*'
 
 Use this helper to derive `<shard_path>` from a checkpoint ID.
 
-Use the reusable executable script to determine the shard path.
-
 ```bash
 # Ensure helper directory exists
 mkdir -p scripts
@@ -505,7 +503,7 @@ Run:
 1. Execute `entire clean --all --dry-run`.
 
 Expected:
-- Dry-run previews orphaned items.
+- Dry-run previews repository-wide Entire data.
 - Preview includes the kinds of items that would be removed.
 - Checkpoint metadata refs/branches are preserved.
 
@@ -717,7 +715,7 @@ The deeper rewind matrix belongs in automated tests. Manual validation here is o
 
 Capture:
 - executed command + full output
-- before/after `git show-ref` snapshots
+- before/after `git show-ref` snapshots when ref state is relevant
 - `git ls-remote` snapshots when remote behavior is involved
 - `git show` and `git ls-tree` evidence for expected files/paths
 - outcome classification: pass/fail/blocked with reason