docs: add CONTRIBUTORS.md and CHANGELOG.md entry for architecture overview PR

- Add CleverThis to CONTRIBUTORS.md contributor list
- Add CHANGELOG.md entry under [Unreleased] for architecture documentation update
  (A2A protocol overview, storage/persistence, LangGraph execution, TUI architecture,
  server roadmap, and milestone progress)

Closes #8763

CHANGELOG.md

@@ -17,6 +17,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Architecture Overview Documentation**: Expanded A2A protocol overview with JSON-RPC envelopes, event streaming, and remote transport; documented storage/persistence, LangGraph execution, TUI architecture, server roadmap, and milestone progress.
+
 - **TDD Issue-Capture Test Activation** (#7025): Replaced 234 bare `@skip` tags
   across 82 Behave feature files with the correct `@tdd_expected_fail @tdd_issue
   @tdd_issue_<N>` tag system. Scenarios whose referenced bugs were already fixed

CONTRIBUTORS.md

@@ -2,6 +2,7 @@
 
 * Aditya Chhabra <aditya.chhabra@cleverthis.com>
 * Brent E. Edwards <brent.edwards@cleverthis.com>
+* CleverThis
 * HAL 9000 <hal9000@cleverthis.com>
 * Hamza Khyari <hamza.khyari@cleverthis.com>
 * Jeffrey Phillips Freeman <jeffrey.freeman@syncleus.com>

docs/architecture.md

@@ -298,8 +298,24 @@ All CLI, TUI, and server interactions cross the A2A boundary
 [ADR-047](adr/ADR-047-acp-standard-adoption.md)):
 
 - **Local mode** — `A2aLocalFacade` maps operations to direct Python calls
-- **Server mode** — `A2aHttpTransport` (stub; full implementation pending)
-- Version negotiation via `A2aVersionNegotiator`
+  and exposes the full `_cleveragents/plan/*` and `_cleveragents/registry/*`
+  surface. Handler dispatch is cached so repeated calls avoid rebuilding the
+  routing table, and domain exceptions are mapped to JSON-RPC error codes by
+  `map_domain_error`.
+- **JSON-RPC 2.0 envelope** — `A2aRequest` / `A2aResponse` enforce the wire
+  contract, generate ULID request identifiers, and require `"jsonrpc": "2.0"`
+  per the spec adopted in ADR-047.
+- **Event streaming** — `A2aEventQueue`, `EventBusBridge`, and
+  `SseEventFormatter` translate plan lifecycle `DomainEvent` objects into
+  Server-Sent Events (`task/statusUpdate`, `task/artifactUpdate`) so the TUI
+  and future server clients can follow progress without polling.
+- **Version negotiation** — `A2aVersionNegotiator` rejects unsupported protocol
+  versions and logs accepted ones, keeping the CLI, TUI, and future server in
+  lock-step.
+- **Remote transport roadmap** — `A2aHttpTransport` is still a stub in local
+  mode; the FastAPI-based JSON-RPC service planned for v3.8.0 will supply the
+  concrete implementation. The lightweight `a2a.asgi` module already exposes
+  Kubernetes health probes for early server deployment testing.
 
 ---
 
@@ -355,6 +371,117 @@ Never construct services directly in application code.
 
 ---
 
+## Storage & Persistence
+
+- Local deployments default to `sqlite:///.cleveragents/db.sqlite` (wired in
+  `Container.database_url`) with SQLAlchemy models in
+  `cleveragents.infrastructure.database.models`. Alembic migrations under
+  `alembic/` keep the schema aligned with the implementation plan.
+- `PlanLifecycleService` operates in dual mode: with a `UnitOfWork` it persists
+  actions, plans, decisions, invariants, and async jobs to SQLite while
+  mirroring writes in an in-memory cache; without a unit of work (tests) it
+  falls back to the cache-only path.
+- Tool executions wrap in `ChangeSetCapture`, emitting deterministic entries via
+  `ChangeSetEntryRepository`. These records drive diff previews, audit logs, and
+  the forthcoming decision timeline features.
+- Git-backed projects apply changes in isolated worktrees (`GitWorktreeSandbox`)
+  so the developer working copy stays clean until Apply succeeds.
+
+---
+
+## LangGraph Execution & Validation Pipeline
+
+- `cleveragents.actor.compiler.compile_actor` converts YAML graph actors into
+  `CompiledActor` bundles with LangGraph node configs, entry/exit validation,
+  and LSP binding metadata.
+- `cleveragents.langgraph.graph.LangGraph` plus
+  `langgraph.bridge.RxPyLangGraphBridge` execute those graphs through the
+  reactive stream router, preserving execution history, state snapshots, and
+  cancellation signals for diagnostics.
+- `cleveragents.tool.router.ToolRouter` normalises OpenAI, Anthropic, and
+  LangChain tool payloads into `ToolCallRequest` objects, invokes
+  `ToolRunner`, and emits `NormalizedToolCallResult` records with validation
+  metadata. `ChangeSetCapture` can wrap any write-capable `ToolSpec` so file
+  mutations feed directly into plan diffs.
+- The apply phase uses `ApplyValidationGate` and the pluggable
+  `ValidationRunner` to execute validation tools, persist pass/fail metadata,
+  and block Apply when mandatory checks fail — groundwork for the v3.2.0
+  Decisions + Validations milestone.
+
+---
+
+## TUI Architecture
+
+- The optional Textual dependency is loaded at runtime; `CleverAgentsTuiApp`
+  composes overlays for help, slash commands, reference insertion, persona
+  management, and the first-run actor selector, with a fallback that explains
+  how to install the extra if Textual is missing.
+- Input flows through `InputModeRouter`, which routes between free-form chat,
+  slash commands (handled by `TuiCommandRouter`), and shell execution guarded by
+  `tui.shell_safety.PatternDetector`. Commands resolve services from the shared
+  DI container so persona, session, and registry operations behave identically
+  to the CLI.
+- Persona state (`tui.persona.state`) tracks per-session presets and scopes, and
+  the permissions overlay (`tui.permissions`) surfaces tool approval requests
+  inline. Session export/import share the same `SessionService` used by the CLI.
+- Milestone v3.7.0 extends this surface with persistent session tabs, checkpoint
+  timelines, and persona presets; the widget scaffolding (`widgets.*`) already
+  contains the overlays and controls those features will inhabit.
+
+---
+
+## Server Roadmap
+
+- `cleveragents.a2a.asgi:app` provides `/live`, `/ready`, and `/health`
+  endpoints so the Helm chart under `k8s/` can deploy probes ahead of the full
+  server build.
+- Remote transport remains stubbed: `A2aHttpTransport` raises
+  `A2aNotAvailableError` for all methods and `A2aEventQueue.subscribe_remote`
+  does the same. The v3.8.0 milestone replaces these stubs with a FastAPI-based
+  JSON-RPC gateway backed by PostgreSQL.
+- Server mode reuses the existing service container; the separation between
+  transport (`facade`, `models`, `events`) and business logic is complete, so
+  only the HTTP layer and database wiring remain.
+
+---
+
+## Milestone Progress
+
+### Completed
+
+- **v3.0.0 – Minimal Local Source-Code Workflow**  
+  Delivered SQLite-backed persistence (`Container.database_url`,
+  `UnitOfWork`), git worktree sandboxing, ChangeSet capture for tool mutations,
+  and actor-driven plan execution in local mode.
+- **v3.1.0 – Actor Compiler + Full LLM Integration**  
+  Landed the LangGraph-based actor compiler, MCP/LSP adapters, the tool router,
+  validation runner, and event queue wiring so CLI/TUI sessions share the same
+  execution pipeline.
+
+### In Flight
+
+- **v3.2.0 – Decisions + Validations + Invariants** — builds on
+  `PlanLifecycleService`, `DecisionService`, and `ApplyValidationGate` to record
+  decision trees, enforce invariants, and surface validation outcomes.
+- **v3.3.0 – Corrections + Subplans + Checkpoints** — extends
+  `GitWorktreeSandbox`, `ChangeSetCapture`, and the subplan tooling to support
+  targeted corrections and checkpoint review.
+- **v3.4.0 – ACMS v1 + Context Scaling** — expands `ContextTierService`,
+  context hydration, and UKO runtime so larger projects can stream curated
+  context to actors.
+- **v3.5.0 – Autonomy Hardening** — hardens guardrails by leveraging
+  `PlanPreflightGuardrail`, shell safety scoring, and the A2A event queue for
+  background monitoring.
+- **v3.6.0 – Advanced Concepts** — introduces additional LLM backends,
+  container execution (`tool.container_executor`), and richer resource types.
+- **v3.7.0 – TUI Implementation** — completes the Textual experience with
+  session persistence, persona presets, and surfacing plan checkpoints.
+- **v3.8.0 – Server Implementation** — ships the FastAPI/JSON-RPC gateway,
+  remote event streaming, and PostgreSQL-backed persistence on top of the
+  existing ASGI/transport scaffolding.
+
+---
+
 ## Key Design Decisions
 
 | Decision | ADR | Summary |