Lesson 20 — Revisions and diffs

Outcome

Capture exact candidate revision identity after agent work and show a diff relative to the intended base.

Why this comes now

Review and verification are meaningless if Forge cannot answer “which exact code did we evaluate?”

Understand

A provider Turn completing does not automatically mean the Review candidate is settled. Forge may still need to inspect Git status, compute the revision/worktree state, and record the candidate. Git identity is the anchor for later validity.

Do not auto-commit user-visible history purely for Forge. If working-tree diffs are the candidate representation early on, define the identity carefully (base revision + worktree state fingerprint or a hidden checkpoint). Simpler first implementation may require/produce commits if your chosen provider workflow already does; document the exact rule.

Build the real project

1. Define CandidateRevision representation.
2. Add post-turn Operation that captures/settles candidate code state.
3. Implement Git diff query against base/candidate.
4. Store enough identity for stale checks.
5. Expose diff file list and hunks through paged/on-demand RPC.
6. Add first diff viewer to Task workspace.

Completion gate

Change code after capturing candidate A and prove Forge detects that the current code no longer matches A. Diff tests cover rename/add/delete/basic binary handling policy.

Pitfalls to avoid

Do not call Turn complete and instantly set Task Review before candidate capture settles. Do not create misleading autosave commits without an explicit policy.

References

git diff, T3 checkpoint/revision separation: https://github.com/pingdotgg/t3code/blob/main/docs/internals/overview.md

Checkpoint

Document the exact candidate-revision identity rule chosen for the first implementation.