feat: trail commit — smart commits from trajectory chapters

[barryonthecape]

Summary

trail commit reads your active/recent trajectory's chapters and decisions to automatically group changed files into logical, well-structured git commits — one per chapter. Each commit gets a rich message derived from the trajectory narrative.

Motivation

When an agent works on a task, it naturally produces changes in logical units (setup, implementation, testing, docs). The trajectory records these as chapters. But when it's time to commit, you typically just do git add . && git commit — lumping everything together.

This command bridges that gap: it uses the trajectory you already created to drive commit structure.

How It Works

1. Finds trajectories with startRef — active or recently completed trajectories that have a _trace.startRef (automatically captured by trail start)
2. Diffs the working tree against startRef to find all changed files (handles the "no new commits yet" case)
3. Groups files by chapter — uses tool_call event raw values to match changed file paths to the chapter that created them
4. Creates commits — one per chapter that has matched files, with a catch-all for unmatched files

Example

Given a trajectory with chapters Setup JWT library, Write auth middleware, and Add tests:

$ trail commit --dry-run
Found 1 trajectory with uncommitted changes.

=== Add user authentication (traj_abc123) ===
Changed files (4): auth/jose.ts, auth/middleware.ts, ...

[1/4] Would commit:
  Subject: chore: Setup JWT library
  Files: auth/jose.ts

[2/4] Would commit:
  Subject: chore: Write auth middleware
  Body: Decisions: Bearer token in Authorization header
  Files: auth/middleware.ts

[3/4] Would commit:
  Subject: feat: Add tests
  Files: auth/middleware.test.ts

[4/4] Would commit:
  Subject: chore: Other changes
  Files: README.md

Commit Message Format

Each commit gets:

• Subject — chapter title with conventional commit prefix (feat:, fix:, chore:, etc.)
• Body — decisions and notable notes from chapter events
• Footer — Trajectory: traj_xxx trailer linking the commit back to the trajectory

feat: Add tests

Trajectory: traj_abc123

Flags

Flag	Description
--dry-run	Preview commits without creating them
--ai	Use an LLM (opencode/codex/claude) to do smarter cross-chapter grouping
--trajectory <id>	Commit only a specific trajectory
--base <ref>	Override the git ref to diff against
--model <model>	Specify LLM model for --ai mode

Key Design Decisions

• .trajectories/ files are excluded from user commits — trajectory metadata stays as a separate "chore" commit
• Staging area is reset between commits — prevents files from previous staging batches from being accidentally committed
• Handles startRef === HEAD — when trail start was called but no commits were made yet, diffs the working tree directly
• Graceful fallback — if AI grouping fails, falls back to naive chapter-based grouping

Todo / Future Work

• Update trajectory's filesChanged array after successful commits
• Support trail complete integration (commit on complete)
• Handle multi-file-per-chapter grouping more intelligently
• Add --amend flag to retroactively amend commits with trajectory info