This note compares the high-level architectural overview with the detailed Phase System Design v2 document, highlighting scope differences, complementarities, and any gaps or tensions.
envoy/architecture-summary operates at a macro-architectural level. It defines the four-layer structure (LLM, orchestrator, IMAP, Notes), core principles (explicit state, structured data, deterministic behaviour), lifecycle rules, and the phase-aware processing model in broad terms.
envoy/design-phases-v2 operates at a micro-architectural level. It refines one subsystem of the architecture — the phase/state machine — specifying model ownership, anti-loop mechanics, dynamic phase availability, and orchestrator responsibilities in detail.
The two documents are therefore complementary: the summary defines the system boundaries and philosophy; v2 defines the mechanics of one critical subsystem.
The architecture summary mentions model tiering (cheaper models for triage/gathering, full models for coding/reasoning) and notes that the LLM may hint the next model via next_model.
Design v2 explicitly removes next_model from the LLM contract and makes model selection a property of the phase note, owned by the orchestrator. This is a deliberate architectural tightening to eliminate circular upgrade decisions and looping behaviour.
This is not a contradiction but an evolution: v2 supersedes the earlier description in the summary. The summary will need updating to remove references to next_model being returned by the LLM.
The architecture summary emphasises deterministic behaviour and explicit state. Design v2 operationalises this principle through idle_count, dynamic phase lists, and forced transitions at idle_count=5.
The anti-loop mechanism directly reinforces the architectural principle of 'Inspectable systems > hidden magic' by making transition pressure explicit and rule-driven rather than heuristic.
The summary describes a 9-phase state machine and phase-aware processing. Design v2 deepens this by defining what a phase note must contain (model, next_phases, force_next, one_shot) and how the orchestrator injects available phases each iteration.
There is no conceptual conflict; v2 formalises and constrains what was previously described more loosely.
1. The architecture summary still references next_model in the EnvoyResponse schema; v2 removes it. The summary should be updated to reflect phase-owned model selection.
2. The summary does not mention idle_count or the dynamic degradation of phase availability. Adding a short subsection on loop prevention would align it with v2.
3. The lifecycle and folder layout sections in the summary are not discussed in v2. This is acceptable, but it highlights that v2 is subsystem-focused rather than system-complete.
envoy/design-phases-v2 is a refinement and hardening of the architecture described in envoy/architecture-summary, particularly around phase control and model governance. There are no direct contradictions, but the summary document is partially outdated regarding model selection and would benefit from revision to align with v2.