Learning Log

Use this for short evidence from building/using Forge that may affect architecture or later lessons. It is not a daily diary.

Template

YYYY-MM-DD — short title

Observed: What actually happened?

Why it matters: What assumption/design could this affect?

Action: No change / update doc / open decision / write ADR / change plan.

---

2026-09-10 — Starter architecture reset

Observed: Earlier Forge work contained valuable research but accumulated a precedence stack where current truth had to be reconstructed from old PRD/TDS text plus later ADRs.

Why it matters: This is costly for both human and AI contributors.

Action: Canonical product/architecture/design docs now remain current; ADRs preserve reasons rather than acting as hidden patches. Previous documents are retained in docs/archive/ only.

2026-09-10 — Lessons from comparable orchestrators

Observed: T3 Code, Sculptor, Emdash, Vibe Kanban, OpenHands, and Mux repeatedly expose failures at lifecycle boundaries: external side effects vs durable state, worktree safety, provider capability semantics, reconnect freshness, large streaming replay, and process/provider ownership.

Why it matters: These are predictable design risks, not theoretical edge cases.

Action: Added durable Operation, Execution Environment, Agent Instance/Strategy capability separation, stable worktree identity, stream/history separation, and explicit sync health to the baseline architecture.