feat(agents): git checkpoints after each feature-agent step (spec 138)

[arielshad]

What

After every feature-agent step that can change files, Shep now snapshots the feature's worktree into a hidden ref, refs/shep/checkpoints/<featureId>/<seq>-<node>, and records it in SQLite. Users can then:

• see what each step changed,
• diff any two steps,
• roll the worktree back to a step, from the CLI or from a new Checkpoints tab in the feature drawer.

Why

Implements specs/138-git-checkpoints/: workstream T4 of the T3 Code review (docs/competitors/t3code.md, "What Shep Should Take" §3).

Until now a run kept only its end state, the branch. Nobody could answer "what did implement change, and what did repair change after it?", or undo one bad step without editing git by hand.

Capture

Capture follows T3's approach and never touches the user's branch, HEAD, index or files:

1. Seed a temporary GIT_INDEX_FILE.
2. add -A, then write-tree.
3. commit-tree with a fixed identity and no signing, then update-ref.

All writes run with core.fsync=objects,reference.

• Where it hooks in. A withCheckpoint wrapper covers every file-changing node of the full, fast and exploration graphs.
• Baseline. A baseline is captured before the first step.
• Unchanged steps. A step that changed nothing records nothing.
• Failures. A capture failure is logged and never fails the run.

Diff

Diffs run git diff between two checkpoint commits and are cached in-process. The unified-diff parser previously in GitPrService (with a hand copy in the GitHub review service) is now one shared module.

Restore

Restore first captures a pre-restore checkpoint, so a restore can itself be undone. It then runs clean -fd, read-tree --reset -u and reset -q. The working tree matches the checkpoint, ignored files are kept, and the branch is not moved, so nothing already pushed is rewritten.

A single CheckpointRestorePolicy gates restore, and the list exposes its answer as a typed CheckpointRestoreBlocker. It refuses unless all three hold:

• the feature has its own worktree, distinct from the repository path;
• git confirms the directory is a linked worktree;
• the latest agent run is not pending or running.

Cleanup

Refs and rows are deleted when the worktree is removed (post-merge cleanup, delete) or the feature is archived (manual or auto-archive).

Data model

• New TypeSpec entity GitCheckpoint.
• Enums GitCheckpointKind and CheckpointRestoreBlocker.
• Migration 170 git_checkpoints. 169 belongs to feat(web): review cleanup — per-area feature flags, ASPM off by default #925, which is merged into this branch.

Screenshots / Recording

Storybook (Features/Checkpoints/*) with fixture data. Light and dark.

	Light	Dark
Per-step diff
Compare two steps
Restore blocked (agent running)
Restore confirmation

Testing

Real git (global/system config isolated, signing off, worktree path with a space): tests/integration/infrastructure/services/git/git-checkpoint.service.test.ts

• Capture leaves git status, HEAD, branch and index unchanged.
• Untracked files are captured; ignored files are not.
• The ref is visible from the main checkout.
• Diff and stat work, and the cache returns the same object.
• Restore equals the checkpoint, keeps ignored files and leaves the branch alone.
• Linked worktree vs main checkout is detected.
• Ref deletion removes only the feature's refs.
• The unborn-branch case works.
• A directory that is not the top of its own work tree is refused, e.g. a leftover worktree directory inside another repository after post-merge cleanup, so the parent checkout is never snapshotted.
• A mutation check passed: without GIT_INDEX_FILE the "index untouched" test goes red.

Repository: tests/integration/infrastructure/repositories/sqlite-git-checkpoint.repository.test.ts (non-default round-trip, UNIQUE per feature, delete, idempotent migration).

Use cases (tests/unit/application/use-cases/features/checkpoints/)

• Baseline and step numbering; unchanged tree skipped.
• Per-step and two-step diffs.
• Every restore refusal; Windows-spelled repository path treated as the same checkout.
• Best-effort delete.

Pipeline: with-checkpoint.test.ts and checkpoint-capture.test.ts, plus graph-level tests asserting which nodes capture in the full, fast and exploration graphs (validate nodes never capture).

Cleanup hooks: archive, auto-archive watcher, worktree cleanup, delete.

CLI: checkpoints.command.test.ts.

Web: checkpoints-tab.test.tsx (per-step, baseline, compare, restore confirm/refusal, blocker, empty, error), plus drawer tab visibility.

DI: the bootstrap test resolves every new token and goes red without the registration.

Storybook: CheckpointList (Default / RestoreDisabled / WithPreRestore / WithoutRestore), CheckpointCompareBar, CheckpointRestoreDialog (Default / Pending / Closed), CheckpointsTab.

Local results, on the tree merged with main:

• lint, format:check, typecheck, check:stories and generate (no drift) all pass.
• test:unit: 15,043 passed.
• test:int: 2,160 passed. The first run had 7 failures in dependency-path-traversal, caused by the unpatched extract-zip I had installed into the sandbox as a stand-in; with the repo patch applied, all pass.
• build, build:web and build:storybook pass.

Checklist

• pnpm lint passes
• pnpm format:check passes
• pnpm typecheck passes
• pnpm test:unit and pnpm test:int pass
• pnpm build succeeds
• (UI only) pnpm build:storybook and pnpm build:web succeed; every new component has a colocated .stories.tsx
• (Domain changes) pnpm generate ran and output.ts plus apis/json-schema/ are committed
• (New use case) Tests landed RED-first per the TDD guide
• No domain/ or application/ file imports anything from infrastructure/
• Commit messages follow Conventional Commits
• Updated LESSONS.md

🤖 Generated with Claude Code

https://claude.ai/code/session_01V37fpj6cexvgoExiG9SHKj

---

Generated by Claude Code