Lesson 23 — Immutable Plans and review rounds

Outcome

Create Feature/Task Plans whose reviewed content is immutable by revision and whose rejection produces a new revision.

Why this comes now

Planning comes after the work/review loop so it can reuse known revision/review ideas instead of creating a second ad-hoc system.

Understand

Plan is identity/lifecycle; PlanRevision is immutable content. A review belongs to the exact PlanRevision. Rejection returns the Plan to Draft for a new revision; it does not mutate the reviewed text. Feature and Task Execution Plans share machinery but produce different outcomes.

Build the real project

1. Add Plan scope, Plan, PlanRevision, PlanReview/annotation models.
2. Implement create revision, submit review, reject, approve commands.
3. Build simple Markdown Plan workspace and revision history.
4. On rejection, carry annotations as context to the next authoring pass without rewriting history.
5. Add Task Execution Plan attachment/use after approval.
6. Keep Feature decomposition for next lesson.

Completion gate

Revision 1 remains readable after revision 2 exists. Review 1 always points to revision 1. Approved Plan identifies the approved revision explicitly.

Pitfalls to avoid

Do not store only plans.content + round. Do not use “decomposed” as a replacement for approved plan status. Do not invent a different review engine for task plans.

References

Original workflow is preserved in docs/archive/00-original-agent-task-orchestrator.md; compare it with current DOMAIN_MODEL.md.

Checkpoint

Update docs/status/CURRENT.md and note whether immutable plan history feels useful in actual use or unnecessarily heavy; evidence can refine the model.