Add trails: branch-centric work tracking

[dipree]

Summary

Trails are branch-centric work tracking abstractions stored on the entire/trails orphan branch. They capture the why/what of a developer's work (human intent), while checkpoints capture the how/when (machine snapshots). Think of them as lightweight, git-native pull request metadata that exist before any PR is opened.

New: entire trail command family

• entire trail — show the current branch's trail, or list all trails if none exists
• entire trail list — list all trails with --status filter and --json output
• entire trail create — create a trail interactively or via flags (--title, --body, --branch, --status, --checkout)
• entire trail update — update trail metadata interactively or via flags (--status, --title, --body, --add-label, --remove-label)

Interactive trail creation flow

1. Prompt for title ("What are you working on?") and optional body
2. Derive branch name from title via slugification (user can override)
3. Select status (draft, open, in_progress, in_review)
4. Create the git branch locally (via go-git SetReference, no checkout by default)
5. Push both the branch and trail data to origin
6. Optionally checkout the branch (--checkout flag or interactive confirm)

Interactive trail update

When entire trail update is run without flags, an interactive form is shown pre-filled with current values (status select, title input, body textarea).

Checkpoint linking

After each condensation (manual-commit PostCommit), the checkpoint is appended to the trail's checkpoints.json (newest first). This links every checkpoint to the trail for the branch.

AI-powered trail title generation

When summarize.enabled is configured and the agent supports TextGenerator (currently Claude Code via claude --print), the trail title and body are generated from the session transcript after the first condensation. Uses Haiku for fast, cheap generation.

Trail author from GitHub

Trail author is resolved via gh api user -q .login (GitHub username), with a fallback to git config user.name.

Remote trail sync

entire trail list fetches the remote entire/trails branch before listing, so trails created by collaborators are visible. Pre-push hooks push the entire/trails branch alongside entire/checkpoints/v1.

New packages & files

File	Description
cmd/entire/cli/trail/trail.go	Types (ID, Status, Metadata, Discussion, CheckpointRef), ValidStatuses(), HumanizeBranchName()
cmd/entire/cli/trail/store.go	Store with full CRUD on entire/trails orphan branch (sharded storage)
cmd/entire/cli/trail/trail_test.go	Unit tests for ID generation, validation, status, humanization
cmd/entire/cli/trail/store_test.go	Integration tests for Store operations
cmd/entire/cli/trail_cmd.go	Cobra commands: trail, list, create, update + helpers (slugify, branch creation, push)
cmd/entire/cli/summarize/trail_title.go	GenerateTrailTitle() — LLM-based title/body from transcript
cmd/entire/cli/agent/claudecode/generate.go	GenerateText() implementation for Claude Code (claude --print)
cmd/entire/cli/agent/agent.go	TextGenerator interface for agents supporting text generation

Modified files

File	Changes
cmd/entire/cli/strategy/manual_commit_hooks.go	Added appendCheckpointToTrail() and generateTrailTitleFromTranscript() after condensation
cmd/entire/cli/strategy/manual_commit_condensation.go	Returns Transcript and Prompts in CondenseResult for trail linking
cmd/entire/cli/strategy/push_common.go	Added PushTrailsBranch() for pushing entire/trails branch (independent of push_sessions setting)
cmd/entire/cli/strategy/manual_commit_push.go	PrePush calls PushTrailsBranch() alongside sessions branch push
cmd/entire/cli/settings/settings.go	Removed IsTrailsDisabled() methods
cmd/entire/cli/paths/paths.go	Added TrailsBranchName constant
cmd/entire/cli/root.go	Registered trail command

Storage format

Trails are stored on the entire/trails orphan branch with sharded paths:

<trail_id[:2]>/<trail_id[2:]>/
├── metadata.json       # Trail metadata (title, body, branch, status, author, etc.)
├── discussion.json     # Comments and replies (future use)
└── checkpoints.json    # Checkpoint references (newest first)

Status lifecycle: draft → open → in_progress → in_review → done → closed

Test plan

• mise run fmt && mise run lint && mise run test:ci passes
• entire trail create — interactive flow creates branch, trail, and pushes both
• entire trail create --title "..." --branch "..." — non-interactive flag mode
• entire trail update — interactive form pre-fills current values
• entire trail update --status in_review --title "New title" — flag mode
• entire trail list — shows trails from both local and remote
• entire trail list --status in_progress --json — filtering and JSON output
• Checkpoint linking after commit condensation

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Touches git-hook/strategy flow and introduces new orphan-branch storage and push behavior, which could affect repository state and hook reliability. LLM-based title generation spawns subprocesses and must remain best-effort to avoid disrupting core checkpointing.

Overview
Introduces Trails, a new branch-centric metadata layer stored on the entire/trails orphan branch, plus a new entire trail command family to create, list/show, and update trail records (including remote fetch for listing).

Hooks/strategies now auto-create a trail on TurnStart for non-default branches, append each new checkpoint to the trail (manual-commit condensation and auto-commit SaveStep), and push entire/trails alongside entire/checkpoints/v1 in PrePush; shadow-branch cleanup/tests are updated to treat entire/trails as non-shadow.

Adds optional agent-driven text generation via agent.TextGenerator with a Claude Code implementation (claude --print) and a new summarize helper to best-effort generate trail titles/descriptions from condensed transcripts when summarization is enabled.

^{Written by Cursor Bugbot for commit 85f50b7. Configure here.}

[Copilot]

Pull request overview

Adds “trails” as a branch-centric work tracking layer stored on an entire/trails orphan branch, integrating it into lifecycle hooks and checkpoint strategies so work intent can be recorded and linked to checkpoints.

Changes:

• Introduces entire trail command family (show/list/create/update) plus supporting trail types and git-backed store.
• Hooks trail auto-creation on TurnStart and links checkpoints to trails for both manual-commit and auto-commit strategies.
• Adds optional agent text generation (TextGenerator) and a summarizer helper to generate trail titles/descriptions from transcripts.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
cmd/entire/cli/trail_cmd.go	Adds Cobra commands and helpers for trail CRUD, display, remote fetch, branch creation, and auto-create helper.
cmd/entire/cli/trail/trail.go	Defines trail domain types (ID/status/metadata/checkpoints) and helpers like branch humanization.
cmd/entire/cli/trail/trail_test.go	Unit tests for IDs, status validation, and branch humanization.
cmd/entire/cli/trail/store.go	Implements git-backed trail storage on entire/trails (CRUD + checkpoint linking).
cmd/entire/cli/trail/store_test.go	Tests Store behavior against a temp git repo using git CLI.
cmd/entire/cli/summarize/trail_title.go	Adds LLM-based trail title/description generation from condensed transcripts.
cmd/entire/cli/strategy/push_common.go	Adds PushTrailsBranch() wrapper to push/sync entire/trails.
cmd/entire/cli/strategy/manual_commit_types.go	Extends condensation result to include prompts and raw transcript bytes for downstream trail features.
cmd/entire/cli/strategy/manual_commit_push.go	Pushes trails branch alongside metadata branch in pre-push hook.
cmd/entire/cli/strategy/manual_commit_hooks.go	Links checkpoints to trails and (best-effort) generates trail title/description after condensation.
cmd/entire/cli/strategy/manual_commit_condensation.go	Plumbs prompts/transcript into CondenseResult.
cmd/entire/cli/strategy/cleanup.go	Excludes entire/trails from shadow-branch cleanup logic.
cmd/entire/cli/strategy/auto_commit.go	Links checkpoints to trails and (best-effort) generates title/description from transcript on SaveStep; pushes trails in pre-push.
cmd/entire/cli/root.go	Registers the new trail command.
cmd/entire/cli/paths/paths.go	Adds TrailsBranchName constant.
cmd/entire/cli/lifecycle.go	Auto-creates trails on TurnStart for non-default branches.
cmd/entire/cli/integration_test/mid_session_commit_test.go	Updates shadow-branch expectations to ignore entire/trails.
cmd/entire/cli/integration_test/deferred_finalization_test.go	Updates shadow-branch expectations to ignore entire/trails.
cmd/entire/cli/agent/claudecode/generate.go	Implements GenerateText() for Claude Code via claude --print.
cmd/entire/cli/agent/agent.go	Adds TextGenerator optional interface for agents.
CLAUDE.md	Documents trails package, commands, storage format, and linkage behavior.
.entire/settings.json	Updates repo settings (wingman enabled, telemetry enabled).

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

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

Comment @cursor review or bugbot run to trigger another review on this PR