docs(spec): add v3.8.0 Server Implementation milestone plan and update status table (#7701)

Co-authored-by: CleverThis <hal9000@cleverthis.com>
Co-committed-by: CleverThis <hal9000@cleverthis.com>

docs/specification.md

@@ -46797,17 +46797,18 @@ The following table shows which Protocol each pipeline slot implements and what
 
 ## Milestone Plan
 
-This section defines the ordered milestone plan for CleverAgents v3.x, mapping architectural features to verifiable deliverables. Each milestone builds on the previous and is independently testable. Milestones v3.0.0 and v3.1.0 are **complete**. This plan covers v3.2.0 through v3.7.0 — the production-ready target.
+This section defines the ordered milestone plan for CleverAgents v3.x, mapping architectural features to verifiable deliverables. Each milestone builds on the previous and is independently testable. Milestones v3.0.0 and v3.1.0 are **complete**. This plan covers v3.2.0 through v3.8.0 — the production-ready target including server mode.
 
-!!! note "Milestone Status (as of 2026-04-08)"
+!!! note "Milestone Status (as of 2026-04-11)"
     - **v3.0.0** ✅ CLOSED — Minimal Local Source-Code Workflow
     - **v3.1.0** ✅ CLOSED — Actor Compiler + Full LLM Integration
-    - **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (85 open / 235 closed)
-    - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (65 open / 108 closed)
-    - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (55 open / 130 closed)
-    - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (486 open / 188 closed)
-    - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (162 open / 150 closed)
-    - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (461 open / 403 closed)
+    - **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (571 open / 257 closed)
+    - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (122 open / 108 closed)
+    - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (200 open / 137 closed)
+    - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (971 open / 201 closed)
+    - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (282 open / 150 closed)
+    - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (526 open / 427 closed)
+    - **v3.8.0** 🔄 IN PROGRESS — Server Implementation (352 open / 132 closed)
 
 ---
 
@@ -47066,6 +47067,60 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
 
 ---
 
+### v3.8.0 — Server Implementation
+
+**Goal**: Implement the CleverAgents server and all server-dependent capabilities using the A2A (Agent-to-Agent) protocol standard. The server enables multi-device collaboration, shared namespaces, team RBAC, and cloud-hosted actor execution via LangGraph Platform.
+
+**Spec Coverage**: [Server and Client Architecture](#server-and-client-architecture), [A2A Protocol](#agent-to-agent-protocol-a2a), [Authentication and Authorization](#authentication-and-authorization)
+
+**Key ADRs**: [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md)
+
+!!! note "Sequencing"
+    v3.8.0 has no deadline. Development effort should focus on M1–M6 (v3.2.0–v3.7.0) first. v3.8.0 work may proceed in parallel but is not on the critical path for local-mode production readiness.
+
+#### Deliverables
+
+| # | Deliverable | Spec Reference | Verifiable Check |
+|---|-------------|----------------|-----------------|
+| 1 | A2A JSON-RPC 2.0 wire format: standard operations (`message/send`, `message/stream`, task lifecycle) | §Server and Client Architecture — Server Presentation Layer | `curl` to A2A endpoint returns valid JSON-RPC 2.0 response |
+| 2 | `_cleveragents/` extension method routing: plan lifecycle, registry CRUD, entity sync, namespace management | §Server and Client Architecture — Extension Methods | `_cleveragents/plan/use` creates a plan via server |
+| 3 | A2A stdio transport (local mode — agent as subprocess) | §A2A Protocol — Local Mode | `agents plan use` routes through A2A stdio transport in local mode |
+| 4 | A2A HTTP transport (server mode — single JSON-RPC endpoint) | §A2A Protocol — Server Mode | CLI connects to remote server via HTTP; all operations functional |
+| 5 | LangGraph Platform RemoteGraph integration for server-side actor execution | §Server Infrastructure — LangGraph Platform | Strategy and execution actors run on LangGraph Platform via RemoteGraph |
+| 6 | Server application structure: FastAPI + A2A SDK server | §Server Application Structure | Server starts, serves Agent Card at discovery endpoint |
+| 7 | API token authentication: `Authorization: Bearer <token>` header | §Authentication and Authorization — API Tokens | Requests without valid token return 401; valid token accepted |
+| 8 | Team RBAC: namespace-scoped read/write/admin permissions | §Authentication and Authorization — Team RBAC | User without write permission cannot create plans in restricted namespace |
+| 9 | Entity sync via `_cleveragents/sync/*` extension methods | §Entity Sync | `_cleveragents/sync/pull` fetches server entities to local registry |
+| 10 | Multi-device experience: shared namespaces accessible from any device | §Multi-Device Experience | Plan created on device A visible from device B via shared namespace |
+| 11 | Shared namespaces: team members access same actors, actions, projects | §Shared Namespaces | Actor in shared namespace usable by all team members |
+| 12 | PostgreSQL backend for server persistence | §Server Infrastructure — Persistence | Server stores plans, decisions, and registry data in PostgreSQL |
+| 13 | Server deployment: Docker container with `docker compose up` | §Server Deployment — Docker | `docker compose up` starts server; health check endpoint returns 200 |
+| 14 | Server deployment: Kubernetes Helm chart | §Server Deployment — Kubernetes | `helm install cleveragents ./charts/cleveragents` deploys to cluster |
+| 15 | `agents server add` registers a remote server in local config | §CLI Commands — server | Round-trip: add server, list shows it, CLI connects to it |
+| 16 | `agents server status` shows server health and version | §CLI Commands — server status | Command exits 0, shows server version and uptime |
+| 17 | Multi-turn interactions forwarded to client: `_cleveragents/fs/*`, `_cleveragents/terminal/*` | §Server Presentation Layer — Multi-Turn | Server-hosted actor can read client-local files via forwarded fs operations |
+| 18 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes |
+
+#### Key Architectural Constraints
+
+- **A2A exclusivity**: The server exposes **only** an A2A JSON-RPC 2.0 endpoint. No REST API, no GraphQL, no admin endpoint.
+- **Shared domain/application layers**: Server and client share identical Domain and Application layer packages. Zero behavioral drift between local and server modes.
+- **LangGraph Platform**: Actor graphs are deployed to LangGraph Platform as separate deployments; server invokes them via RemoteGraph. The server does NOT run actor graphs in-process.
+- **PostgreSQL schema**: Server uses the same schema as the SQLite client database, with PostgreSQL-specific extensions for multi-tenancy (namespace isolation, team membership).
+- **Authentication boundary**: All A2A requests require a valid API token. Tokens are scoped to a namespace; team RBAC controls per-namespace permissions.
+- **Extension method routing**: `_cleveragents/` methods are routed to Application-layer services. Standard A2A operations (`message/send`, etc.) are routed to `SessionWorkflow` and actor execution.
+- **Multi-turn forwarding**: When a server-hosted actor needs client-local resources (files, terminal), it sends a `_cleveragents/fs/*` or `_cleveragents/terminal/*` request back to the connected client via the A2A task `input-required` mechanism.
+
+#### Definition of Done
+
+- All 18 deliverables verified by automated tests
+- `nox` passes with coverage ≥ 97%
+- No open P0/P1 bugs in v3.8.0 milestone
+- Server starts, accepts A2A connections, executes plans via LangGraph Platform, and persists to PostgreSQL
+- CLI connects to remote server; all plan lifecycle operations functional in server mode
+
+---
+
 ### Cross-Milestone Quality Gates
 
 These quality gates apply to **every milestone** and must pass before a milestone is considered complete: