Lesson 22 — Human review and change requests

Outcome

Complete the core rinse-and-repeat quality loop: review candidate A, request changes, produce B, mark old evidence stale, and human-approve B to Done.

Why this comes now

This is the heart of the product. Everything before this was infrastructure needed to make this loop reliable.

Understand

Review is a record against one exact revision, not a Task status subtype. Human and AI reviewers are reviewer kinds. Requesting changes moves the Task back to Working and creates a later agent Turn/Run with review feedback as context. Approval applies only to the current candidate.

Acceptance criteria, verification, comments, and assumptions eventually appear together because they are different evidence for the same human judgement.

Build the real project

1. Add Review and ReviewComment.
2. Bind Review to CandidateRevision.
3. Build Review workspace: file tree/diff, criteria, verification, comments.
4. Add RequestChanges command that validates the Review is current and returns Task to Working.
5. Feed review feedback into a new agent Turn (fresh Run is acceptable initially if resume semantics are complex).
6. Capture candidate B and show review/verification A stale.
7. Add ApproveTask command with current-review checks.
8. Add optional reviewer-kind model but do not require AI review for human approval unless later policy says so.

Completion gate

End-to-end acceptance exactly follows A → review → changes → B → stale A evidence → review B → human approve → Done. Illegal approval of stale revision fails.

Pitfalls to avoid

Do not add agent_review or human_review Task statuses. Do not let UI call generic UpdateTask(status=DONE). Do not assume review comments belong forever to mutable line numbers after revision changes.

References

Plannotator (integration inspiration): https://github.com/backnotprop/plannotator ; PRD.md.

Checkpoint

M8 is complete. Use Forge on a small real change before adding Planning; write down every point where the review loop felt confusing or slow.