Adds checkpoint-focused explanations and a branch-aware default view to entire explain by gtrrz-victor · Pull Request #112 · entireio/cli

gtrrz-victor · 2026-01-28T02:57:54Z

Note

Medium Risk
Changes explain’s default behavior and adds new checkpoint lookup paths that traverse git history and shadow branches, which could affect performance and edge-case correctness on unusual repos. No auth/security-sensitive logic is touched.

Overview
entire explain now defaults to a branch checkpoints view instead of requiring an active session, listing committed and reachable temporary (shadow) checkpoints grouped by checkpoint/session and filtered against the repo’s default branch.

Adds --checkpoint/-c to explain a single checkpoint by ID or prefix, with --short and --full verbosity (including transcript output), and improves commit explain to recognize Entire-Checkpoint trailers and backfill session IDs via checkpoint metadata.

Refactors default-branch/ancestry detection into shared strategy helpers (GetDefaultBranchName, IsOnDefaultBranch, IsAncestorOf) and extends the checkpoint store with ListAllTemporaryCheckpoints; updates and expands unit/integration tests accordingly.

^{Written by Cursor Bugbot for commit 387eacf. This will update automatically on new commits. Configure here.}

Add TDD tests for --checkpoint, --verbose (-v), and --full flags that will be implemented on the explain command. These tests verify the flags exist but are expected to fail until the flags are added. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: d599f72ee73a

Add three new flags to the explain command: - --checkpoint: explain a specific checkpoint by ID or prefix - --verbose/-v: show prompts, files, and session IDs - --full: show complete transcript Flags are registered but not yet wired to runExplain. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: ec6d3a8b5152

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: b53cfcd0f538

- Update runExplain signature to accept checkpointID, verbose, full params - Add mutual exclusivity check for --session, --commit, --checkpoint - Wire up flags in newExplainCmd RunE - Add runExplainCheckpoint stub - Update TestExplainBothFlagsError to use new signature Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 95648a30fde0

TDD Red phase: test expects runExplainCheckpoint to return "checkpoint not found" error for nonexistent checkpoints. Currently fails because stub returns "not implemented". Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 95648a30fde0

Add checkpoint lookup functionality to runExplainCheckpoint: - Open git repository and create GitStore - List committed checkpoints from entire/sessions branch - Find checkpoint by prefix match - Return "checkpoint not found" error if no match - Load checkpoint data using ReadCommitted - Call formatCheckpointOutput stub for formatting Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 8bc5137450f6

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 5d2a9aa7b90d

Add formatCheckpointOutput function with tiered output levels: - Default: checkpoint ID, session ID, timestamp, token count, intent - Intent is extracted from first line of prompts as fallback - Token count is sum of input, cache creation, cache read, and output Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 102b7007badc

Verbose mode (--verbose, -v) adds: - Files section with list of touched files - Full prompts section (not just first line) Test: TestFormatCheckpointOutput_Verbose Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 102b7007badc

Full mode (--full) adds transcript section showing complete JSONL transcript content in addition to verbose output. Test: TestFormatCheckpointOutput_Full Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: e6d2bbd73e25

- TestExplain_CheckpointNotFound: verify error for nonexistent checkpoint - TestExplain_CheckpointMutualExclusivity: verify mutual exclusivity - Renamed TestExplain_BothFlagsError -> TestExplain_MutualExclusivity - Updated error message check to 'cannot specify multiple' Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 9e5aa3277660

Use sb.Write(result.Transcript) instead of sb.WriteString(string(...)) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: e6d2bbd73e25

- Add --checkpoint flag to short and long descriptions - Document tiered verbosity levels (default, --verbose, --full) - Note mutual exclusivity of --session, --commit, --checkpoint Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: e6d2bbd73e25

Add commitMessage parameter to formatCheckpointOutput function. In verbose/full mode, if a commit message is found for the checkpoint, display it in a 'Commit:' section. The commit message is looked up by searching git history for commits with an Entire-Checkpoint trailer matching the checkpoint ID. Tests: - TestFormatCheckpointOutput_Verbose: verifies commit message is shown - TestFormatCheckpointOutput_Verbose_NoCommitMessage: verifies no section when commit message is empty - TestFormatCheckpointOutput_Full: verifies commit message in full mode Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: e12c3e2b3f2a

Reorder verbose output sections: 1. Commit message (if available) 2. Files 3. Prompts Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 48cfe773289f

Replace sb.WriteString(fmt.Sprintf(...)) with fmt.Fprintf(&sb, ...) for more efficient writes without intermediate string allocation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: ba5e23ccb05b

…put-checkpoint-flag

Instead of failing with "session not found" when the current session has no checkpoints yet, show a helpful overview listing available sessions that the user can explore. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 737e6e3ea2ad

Replace session-focused default with branch-focused view showing all checkpoints grouped by date. Includes [Task] and [committed] indicators, session prompts, and consistent formatting. - Add formatBranchCheckpoints with date grouping - Extract magic numbers to named constants - Update integration tests for new behavior Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 0999195c12b1

…put-checkpoint-flag

Update explain.go and explain_test.go to use the new id.CheckpointID type instead of raw strings for checkpoint IDs: - Change function signatures to take id.CheckpointID - Use trailers.ParseCheckpoint instead of paths.ParseCheckpointTrailer - Use id.MustCheckpointID in tests for type safety - Change checkpoint.TokenUsage to agent.TokenUsage Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: c1c35c964733

…filtering Query checkpoints directly from the checkpoint store instead of through strategy.GetRewindPoints(). On feature branches, only show checkpoints unique to that branch (not reachable from main). On main branch, show all checkpoints up to limit. Fixes issue where checkpoints from main appeared after merging main into a feature branch. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 8ccdd0fbae20

- Group commits by checkpoint ID instead of showing one line per commit - Show prompt once per checkpoint (quoted for actual prompts, unquoted for "(no prompt)") - Remove [committed] indicator (only show [temporary] for uncommitted checkpoints) - Include date on every commit line (MM-DD HH:MM format) - Show git SHA in parens followed by commit message - Count shows unique checkpoints, not total commits - Remove unused dateGroupFormat and timeFormat constants Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f9df612e4bbe

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f9df612e4bbe

Temporary checkpoints store their metadata (including prompt.txt) in the shadow branch commit tree, not in the entire/sessions branch. This fix reads the prompt from the correct location. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f5dab3d95bc1

Add hasCodeChanges() function to filter temporary checkpoints that: - Have no parent (first commit on shadow branch = baseline copy) - Only modify .entire/ metadata files (transcript saves without code changes) This keeps the explain output focused on meaningful code changes rather than periodic transcript saves. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 326f80f02739

- Use ~sha format (11 chars) for temporary checkpoints to distinguish from committed checkpoint IDs (12 chars) - Add explainTemporaryCheckpoint() to handle `explain -c ~sha` lookups - Read prompts from shadow branch tree for temporary checkpoints Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: c642f15679d1

…y] header - Replace per-commit *sha IDs with single [temporary] group for all uncommitted checkpoints - Show git SHA in parentheses for individual commits within the group - Update -c flag to try committed checkpoints first, then fall back to temporary by git SHA prefix - Remove redundant [temporary] indicator when group ID is already "temporary" Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f0ae7ca930f0

- Replace --verbose flag with --short flag - Default checkpoint view now shows prompts, files, and commit message - Use --short (-s) to get summary-only view - Update help text to reflect new defaults Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

cmd/entire/cli/explain.go

- Update help text to reflect default branch view behavior - Add ambiguous prefix detection for committed checkpoints - Add ambiguous prefix detection for temporary checkpoints - Fix isTask flag not updated in groupByCheckpointID loop - Fix misleading "Log error" comment - Use repo-aware strategy.IsOnDefaultBranch instead of cli helper - Add nil check in runExplainCommit for ReadCommitted result - Replace truncateString with strategy.TruncateDescription - Make TestRunExplainCheckpoint_NotFound hermetic (create temp repo) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 7 comments.

cmd/entire/cli/explain.go

cmd/entire/cli/strategy/common.go

cmd/entire/cli/explain_test.go

cmd/entire/cli/explain.go

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f9f6f611b469

…put-checkpoint-flag

Previously, all temporary checkpoints were grouped under a single "temporary" group, losing per-session prompt information. Now they are grouped by session ID, preserving each session's prompt. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

cmd/entire/cli/explain.go

cmd/entire/cli/strategy/common.go

- Use Committer.When instead of Author.When for RewindPoint.Date to match git log traversal ordering (rebases can cause mismatch) - Log errors from getBranchCheckpoints instead of silently swallowing - Update group.prompt if first point has empty prompt but later has one - Remove stray // line in GetDefaultBranchName doc comment - Fix test message from --verbose to --full - Return informative error for ambiguous temporary checkpoint prefixes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 326f190bd6e7

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cmd/entire/cli/explain.go

- Capitalize [task] to [Task] for consistency with other CLI output - Consolidate isAncestorOf to strategy/common.go (fixes missing iter.Close() in auto_commit.go version) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 33b1e1e1b51d

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 5 comments.

cmd/entire/cli/explain.go

cmd/entire/cli/explain_test.go

- Return error for ambiguous temporary checkpoint prefixes (consistent with committed checkpoint behavior, exits non-zero) - Add missing IsTaskCheckpoint/ToolUseID/Agent fields from cpInfo to RewindPoint - Convert test log-only checks to real assertions for detached HEAD and filtering - Optimize branch filtering: precompute reachable-from-main set once instead of calling IsAncestorOf per commit (O(N+M) instead of O(N*M)) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: be671ddd7286

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 4 comments.

cmd/entire/cli/explain_test.go

cmd/entire/cli/explain.go

cmd/entire/cli/strategy/common_test.go

- Rename TestFormatCheckpointOutput_Default to _Short (test was actually testing verbose=false, not CLI default which is verbose=true) - Use GetDefaultBranchName() for branch filtering in getBranchCheckpoints() to handle repos with non-standard default branches (trunk, develop, etc.) - Use store.GetTranscriptFromCommit() for temp checkpoint transcript reading to handle chunked and legacy transcript layouts - Fix GetDefaultBranchName() to use resolved=false to properly read symbolic refs like origin/HEAD - Add test for origin/HEAD symbolic ref path in GetDefaultBranchName Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: fe0dc62dd084

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 4 comments.

cmd/entire/cli/explain.go

- Make --short and --full flags mutually exclusive to prevent contradictory output - Search ALL shadow branches when looking up temporary checkpoints by SHA prefix, not just the shadow branch for current HEAD (fixes lookups when HEAD advanced) - Include temporary checkpoints from all reachable shadow branches in branch view, filtering by whether base commit is in HEAD's history - Handle unborn HEAD (no commits yet) gracefully instead of erroring Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 12215e9ee4bf

khaong and others added 30 commits January 21, 2026 17:53

test(explain): add failing test for mutual exclusivity

51a7ff0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: b53cfcd0f538

test(explain): add failing test for default checkpoint format

40893d7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 5d2a9aa7b90d

style: apply gofmt optimization for transcript output

54afbbe

Use sb.Write(result.Transcript) instead of sb.WriteString(string(...)) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: e6d2bbd73e25

refactor(explain): move commit message before files list

3ecb434

Reorder verbose output sections: 1. Commit message (if available) 2. Files 3. Prompts Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: 48cfe773289f

style(explain): use fmt.Fprintf for string builder writes

d719ff8

Replace sb.WriteString(fmt.Sprintf(...)) with fmt.Fprintf(&sb, ...) for more efficient writes without intermediate string allocation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: ba5e23ccb05b

Merge remote-tracking branch 'origin/main' into alex/ent-109-text-out…

b4a7bb1

…put-checkpoint-flag

Merge remote-tracking branch 'origin/main' into alex/ent-109-text-out…

c29a22e

…put-checkpoint-flag

Merge remote-tracking branch 'origin/main' into alex/ent-109-text-out…

5457fb4

…put-checkpoint-flag

feat(explain): add -c shorthand for --checkpoint flag

ba9ae1a

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f9df612e4bbe

cursor bot reviewed Jan 28, 2026

View reviewed changes

cmd/entire/cli/explain.go Show resolved Hide resolved

Copilot AI review requested due to automatic review settings January 28, 2026 23:08

Copilot started reviewing on behalf of khaong January 28, 2026 23:08 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes

khaong and others added 3 commits January 29, 2026 12:22

style: fix gofmt formatting

c74bdb7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Entire-Checkpoint: f9f6f611b469

Merge remote-tracking branch 'origin/main' into alex/ent-109-text-out…

b87e0d5

…put-checkpoint-flag

Copilot AI review requested due to automatic review settings January 29, 2026 01:31

Copilot started reviewing on behalf of khaong January 29, 2026 01:31 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

cmd/entire/cli/explain.go Show resolved Hide resolved

cmd/entire/cli/explain.go Show resolved Hide resolved

cmd/entire/cli/strategy/common.go Outdated Show resolved Hide resolved

cursor bot reviewed Jan 29, 2026

View reviewed changes

cmd/entire/cli/explain.go Show resolved Hide resolved

Copilot AI review requested due to automatic review settings January 29, 2026 03:37

Copilot started reviewing on behalf of khaong January 29, 2026 03:37 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

khaong requested a review from Copilot January 29, 2026 03:59

Copilot started reviewing on behalf of khaong January 29, 2026 03:59 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

cmd/entire/cli/explain_test.go Outdated Show resolved Hide resolved

cmd/entire/cli/explain.go Outdated Show resolved Hide resolved

cmd/entire/cli/explain.go Outdated Show resolved Hide resolved

cmd/entire/cli/strategy/common_test.go Show resolved Hide resolved

khaong requested a review from Copilot January 29, 2026 04:14

Copilot started reviewing on behalf of khaong January 29, 2026 04:15 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

cmd/entire/cli/explain.go Show resolved Hide resolved

cmd/entire/cli/explain.go Outdated Show resolved Hide resolved

cmd/entire/cli/explain.go Outdated Show resolved Hide resolved

cmd/entire/cli/explain.go Outdated Show resolved Hide resolved

khaong enabled auto-merge January 29, 2026 04:31

khaong approved these changes Jan 29, 2026

View reviewed changes

khaong merged commit b386f5f into main Jan 29, 2026
4 checks passed

khaong deleted the alex/ent-109-text-output-checkpoint-flag branch January 29, 2026 04:41

Conversation

gtrrz-victor commented Jan 28, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

gtrrz-victor commented Jan 28, 2026 •

edited by cursor bot

Loading