Repository Lessons — What Forge Adopts

This page is the compact architecture-review result from T3 Code, Sculptor, Emdash, Vibe Kanban, OpenHands, and Mux. Detailed notes and links live beside this file.

Boundary lessons

1. Task, Agent Run, Agent Turn, and OS process are different lifetimes. Do not make process mechanics the domain identity.
2. Agent Adapter and Execution Environment are independent. “Who/how” and “where” should compose.
3. Driver, configured Instance, and Strategy are different. Capabilities belong to the actual strategy.
4. Clients do not own Git/filesystem/provider state. The Go core/environment owns execution; renderer is a client.
5. Provider-specific protocol behavior stays behind adapters. No provider-name branches throughout the domain/UI.

Reliability lessons

6. External side effects happen after durable intent. Database state and process/filesystem actions cannot be one transaction.
7. Operation retry requires idempotency/reconciliation, not generic retry loops.
8. Provider completion, Turn completion, and post-turn candidate settling are separate.
9. Raw input is retained before parsing. Parser bugs should be recoverable.
10. Worktree creation/cleanup is a lifecycle. Verify reality and never destroy unrecoverable work.
11. Stable filesystem paths use immutable IDs. Renames must not silently invalidate provider sessions.
12. Migrations are product compatibility code. Test upgrades from old fixtures.

Performance/sync lessons

13. Live streaming and historical storage are different representations. Do not replay a token firehose as history.
14. Bound replay; snapshot large gaps.
15. Batch/coalesce UI updates. Publishing full client state per historical delta becomes extremely expensive.
16. Connection alive does not mean subscription/data fresh. Track Sync Health separately.
17. Large histories are paged and virtualized. Local does not mean unbounded is cheap.

Human-control lessons

18. Structured escalation beats transcript inference. A supervisor cannot infer decisions the model never verbalized.
19. Injected tools must be verified as callable. Registration alone is not proof.
20. Conversational involvement and host permission gating are separate axes.
21. Agent claims and observed facts are distinct. Never merge them in the data model.
22. No silent fallback to weaker semantics. If a strategy loses resume/Decision/safety guarantees, report it explicitly.

These rules are reflected in the current architecture and ADRs. Do not copy implementation details from the source repos blindly; copy the lesson and fit it to Forge's smaller product.