# Architecture

## Overview

CoreCI Chat v0.1 is a multi-tenant SaaS with a TypeScript control plane, a Go Relay Agent distributed to customer Linux hosts, an OpenAI-compatible BYOM routing layer, and (M2) an MCP capability broker gateway with four Day-1 infrastructure adapters. The control plane runs in a single AWS region (us-east-1) and enforces tenant isolation via Postgres Row-Level Security. Every request flows through an API gateway that authenticates the session, resolves the tenant, enforces RBAC, and writes an immutable audit entry. The Relay Agent is an outbound-only WebSocket client that registers as a target and heartbeats to the control plane; in M2 it receives MCP tool calls (SSH) and enforces a fixed command whitelist (defense-in-depth layer 2; the broker is layer 1). All credentials live in AWS Secrets Manager (prod) or a local-encrypted fallback (dev) behind a `SecretProvider` interface — never env vars, config files, or DB columns.

The v0.1 wedge is read-only diagnostic: no write actions, no hosted inference, no remediation. Async durable execution is provided by Trigger.dev (instrumented in M3 for chat workflows; the runtime bootstrap lands in M1 Wave A so M3 plugs in cleanly).

### M2 addition — MCP capability broker

M2 introduces the Model Context Protocol (MCP) capability broker as the structured layer between the LLM/UI and customer infrastructure. The broker enforces INV-7 (read-only by default) as the load-bearing safety boundary: it maintains a closed, enumerated tool registry (9 tools across 4 adapters), a per-adapter write-method blocklist, token-bucket rate limiting, multi-target scope disambiguation, and SSE streaming. The broker implements MCP spec version `2025-06-18`. Conformance is verified against modelcontextprotocol.io (artifact required at M2 gate). M3 consumes the broker's REST+SSE gateway as a stable contract (M2 spec §9).

**MCP transport architecture (D-007):** three layers:
1. **Broker ↔ Proxmox/GitHub/Gitea adapters:** in-process custom MCP transport. JSON-RPC 2.0 messages (`tools/list`, `tools/call`) passed in-process between the broker and the TS adapter modules. MCP `2025-06-18` allows custom transports provided they preserve the JSON-RPC message format and lifecycle requirements. No subprocess spawning for same-process TS modules.
2. **Broker ↔ SSH adapter:** the MCP `tools/call` JSON-RPC layer sits between the broker and the TS SSH adapter module (in-process). The TS SSH adapter module then calls the M1 Relay Agent (Go binary) over WebSocket — this downstream WebSocket transport is inherited from M1 infrastructure and is downstream of the JSON-RPC layer. It does not affect MCP conformance.
3. **Broker ↔ CI/LLM smoke:** stdio transport (JSON-RPC over stdin/stdout) for the CI `packages/llm-mock` smoke test. The mock LLM acts as an MCP host.

**Broker ↔ UI:** REST facade + SSE (NOT MCP Streamable HTTP — a browser-friendly facade with MCP-compliant tool schemas and results inside). `POST /api/mcp/invoke` returns `{correlationId, streamUrl}`; `GET /api/mcp/stream/:correlationId` is the SSE stream.

**OpenAI ↔ MCP translation contract:** `tool_calls[].function.{name, arguments}` (OpenAI) → `params.{name, arguments}` (MCP, parsed JSON object); `result.content[].text` + `isError` (MCP) → OpenAI tool message `{role:"tool", tool_call_id, content}`. Documented as a typed translator module in `packages/mcp/translator.ts`.

### Init-time invariants (preserved by the architecture-drift guard)
- Single git repository at `~/coreci-chat`, branch hierarchy `main → milestone/v0.1-bootstrap → phase/NN-*`.
- `.ciagent/` reference files at repo root (single-project mode).
- Release target: Gitea `coreci/coreci-chat` at `https://git.cloudinit.dev`.
- Autonomy: `full` (no HITL after clarify; decision threshold 0.6).

### Architecture invariants (M1 → v0.1)
- Every HTTP request hits the API gateway first: auth → tenant resolve → RBAC → audit.
- Every DB query runs under `SET app.tenant_id = ?` via a session-scoped transaction; RLS policies enforce scoping. Cross-tenant queries return empty.
- Every credential is resolved via `SecretProvider.get(tenantId, key)`; the provider abstracts AWS Secrets Manager (prod) and local-encrypted (dev/test).
- Every auditable event (prompt, tool call, SSH command, response) is appended to `audit_log` with a `prev_hash → curr_hash` chain; `UPDATE`/`DELETE` are REVOKE'd from the app role; a write failure halts the enclosing operation (REQ-038 Edge 7).
- Every LLM inference call is routed to the tenant's configured BYOM endpoint via an OpenAI-compatible `/v1/chat/completions` contract; unconfigured/unreachable → reject with actionable error (REQ-009).
- The Relay Agent makes only outbound connections (WebSocket to SaaS). No inbound firewall rules on customer hosts.

### Architecture invariants (M2 addition)
- **INV-7 at the broker (load-bearing):** 100% of write-action requests rejected at the MCP broker (HTTP 403) before adapter invocation. The broker is the load-bearing safety boundary, NOT the adapter. Per-adapter write-method blocklist: Proxmox POST/PUT/DELETE; SSH non-whitelist commands; GitHub scopes outside `metadata:read`+`actions:read`; Gitea POST/PUT/DELETE/PATCH on all endpoints. Verified by a test per adapter at the M2 gate.
- **Closed tool registry (REQ-015):** 9-tool starter set locked. Per-tenant policy may disable individual tools but never add new ones. Additions require spec amendment (v1.2+).
- **Defense-in-depth for SSH (REQ-021, REQ-026):** broker validates `command` against the 6-command whitelist subset BEFORE dispatch to Relay Agent (layer 1); M1 Relay Agent `CheckCommand` validates at execution (layer 2). Both layers must pass; either rejecting → HTTP 403 + `adapter.write_rejected` audit event.
- **MCP capability invocations run under `withTenant` + RLS (INV-2):** every capability invocation runs in a tenant-scoped transaction. Adapters are per-tenant; no cross-tenant adapter sharing.
- **Adapter credentials via SecretProvider (INV-3):** all adapter credentials (Proxmox token, GitHub/Gitea PAT, SSH registration token) resolved via `SecretProvider.get`. Credentials never logged; secret identifiers hashed in audit events.
- **Audit completeness for adapter events (INV-4):** new event types appended to M1's `audit_log`: `adapter.configured`, `adapter.test_connection.{succeeded,failed}`, `adapter.capability_invoked`, `adapter.write_rejected`. All hash-chained, append-only, UPDATE/DELETE REVOKE'd.
- **Rate limiting (REQ-019):** token-bucket per user (60 req/min) and per tenant (300 req/min). In-memory, process-local in M2. Capacity = rate; refill 1/sec (user) / 5/sec (tenant).
- **SSE streaming (REQ-017):** per-call streams with ULID correlation IDs. Client disconnect cancels in-flight adapter call; no audit event for client-side cancellation.
- **M1 non-regression:** all M1 REQs (001-014, 038-040) remain passing. No schema, invariant, or behavioral changes to M1 systems except additive (new tables, new audit event types).

## Components

### apps/control-plane (TypeScript, Next.js App Router API routes + standalone services)
- **Description**: API gateway, tenant resolution, RBAC enforcement, BYOM registry/validation/routing, Relay Agent WebSocket server, audit writer, secret provider bootstrap, dashboard (Next.js). Hosts the admin dashboard in M1; the chat UI lands here in M3.
- **Boundaries**: All inbound HTTP/WebSocket enters here. Owns the Postgres connection and the `SET app.tenant_id` discipline. Owns the Trigger.dev runtime bootstrap.
- **Depends on**: `packages/db`, `packages/auth`, `packages/audit`, `packages/secrets`, `packages/config`, Trigger.dev, WorkOS, AWS Secrets Manager.

### apps/relay-agent (Go)
- **Description**: Single static binary. Outbound WebSocket client to the control plane; registration (tenant/target/hostname/OS/IP/version); heartbeat + exponential-backoff reconnect (max 5 → alert); systemd service; SSH whitelist file format + enforcement hook (the SSH adapter plugs into the hook in M2 — no SSH execution in M1).
- **Boundaries**: No inbound ports. Reads its tenant registration token from a local config written by the install script (token resolves to a secret-manager reference, never the raw secret). All state is in-memory or on the control plane.
- **Depends on**: control-plane WebSocket endpoint; systemd; the fixed SSH whitelist file shipped alongside the binary.

### apps/dashboard (Next.js, part of apps/control-plane in M1)
- **Description**: Tenant admin dashboard surfaced in the same Next.js app. M1 surfaces Relay Agent status (green/yellow/red), target hostname, last 100 log lines, BYOM config + validation, RBAC user/role management. Per-tenant view under RLS.
- **Boundaries**: Server components read via the same API gateway (no DB access bypassing RLS). Client components subscribe to a status WebSocket fan-out.
- **Depends on**: `apps/control-plane` API, `packages/auth`.

### packages/db (TypeScript)
- **Description**: Postgres schema, migrations, RLS policies, the `withTenant(tenantId, fn)` helper that sets `app.tenant_id` and runs `fn` in a transaction. Tables: `tenants`, `users`, `tenant_memberships` (user × tenant × role), `targets`, `byom_endpoints` (URL in DB, key ref to secret manager), `audit_log` (append-only, hash-chain), `invitations`. All tenant-scoped tables carry `tenant_id` and an RLS policy.
- **Boundaries**: The ONLY module that opens a Postgres connection. App role has INSERT/SELECT on `audit_log` only; UPDATE/DELETE REVOKE'd. Schema migrations run via a gated migrator.
- **Depends on**: Postgres 16.

### packages/auth (TypeScript)
- **Description**: WorkOS SSO/SAML integration, session management, tenant resolution middleware, RBAC role → route permission map (Admin/Operator/Viewer). Enforces RBAC at the API gateway from the first endpoint (REQ-005 pattern).
- **Boundaries**: Sessions are httpOnly cookies; tokens never logged. WorkOS is the only IdP in v0.1.
- **Depends on**: WorkOS SDK, `packages/db`.

### packages/audit (TypeScript)
- **Description**: Append-only audit writer. Computes `curr_hash = sha256(prev_hash || canonical_payload)`. Payload includes tenant_id, user_id, target_id (for SSH), timestamp, correlation_id, event_type, event_body. On write failure: throws `AuditWriteHaltError` → enclosing operation halts + admin alert (REQ-038 Edge 7).
- **Boundaries**: Never exposes UPDATE/DELETE. Read path is admin-export only (no query UI in MVP — spec §2.2).
- **Depends on**: `packages/db`.

### packages/secrets (TypeScript)
- **Description**: `SecretProvider` interface with two impls: `AwsSecretsManagerProvider` (prod, us-east-1, KMS-backed) and `LocalEncryptedProvider` (dev/test, AES-256-GCM with a key from an env var only for the master key — the master key is the ONE allowed env var, everything else is provider-resolved). Every tenant credential (BYOM key, Proxmox token, SSH key, Git token) is stored/retrieved via `provider.put(tenantId, name, value)` / `provider.get(tenantId, name)`.
- **Boundaries**: Secrets never logged, never written to DB columns, never in config files. The DB stores only a reference (e.g. `aws-sm:coreci/<tenantId>/byom`).
- **Depends on**: AWS SDK (prod), Node crypto (dev).

### packages/config (TypeScript)
- **Description**: Typed config loading (env-aware: prod/staging/dev/test). Loads non-secret config only. The only env vars consumed here are infra-level (DATABASE_URL, WORKOS_API_KEY, AWS_REGION, SECRET_MASTER_KEY_DEV, TRIGGER_API_KEY). All tenant/customer secrets go through `packages/secrets`.
- **Boundaries**: Never reads tenant secrets directly.
- **Depends on**: nothing.

## Components (M2 addition)

### packages/mcp (TypeScript — NEW in M2)
- **Description**: The MCP capability broker gateway. Implements MCP spec version `2025-06-18`. Contains: (1) the closed tool registry (9 tools, REQ-015); (2) the adapter router (REQ-016) resolving `(tenant_id, adapter_type, target_id)` tuples to adapter instances; (3) the write-method blocklist enforcer (REQ-018, INV-7 — the load-bearing safety boundary); (4) the token-bucket rate limiter (REQ-019, in-memory, capacity = rate); (5) the SSE stream manager (REQ-017, per-call streams, ULID correlation IDs); (6) the OpenAI ↔ MCP translator module (`translator.ts`); (7) the in-process custom MCP transport for broker ↔ adapter JSON-RPC.
- **Boundaries**: The broker NEVER invokes an adapter for a write-capable method. The broker validates SSH `command` against the whitelist subset BEFORE dispatch (defense-in-depth layer 1). All capability invocations run under `withTenant` + RLS.
- **Depends on**: `packages/db` (withTenant, adapter config rows), `packages/audit` (adapter event types), `packages/secrets` (adapter credentials), `packages/auth` (RBAC), `packages/config`.

### packages/mcp/adapters/proxmox (TypeScript — NEW in M2)
- **Description**: Read-only Proxmox VE adapter. PVE API client over HTTPS (cookie-based auth). Capabilities: `proxmox.list_vms` (inventory, `GET /api2/json/nodes/{node}/qemu`), `proxmox.get_vm_status` (live, `GET /api2/json/nodes/{node}/qemu/{vmid}/status/current`), `proxmox.get_node_metrics` (live, `GET /api2/json/nodes/{node}/status`). Validates `PVEAuditor` role at config submit time (REQ-025). Write-method blocklist: POST/PUT/DELETE.
- **Boundaries**: Calls only GET endpoints. Token stored via `SecretProvider.set` (INV-3).
- **Depends on**: `packages/mcp` (broker), `packages/secrets`, `packages/audit`.

### packages/mcp/adapters/ssh (TypeScript — NEW in M2)
- **Description**: Read-only SSH/Linux adapter via M1 Relay Agent. The MCP `tools/call` JSON-RPC layer is in-process (broker → TS SSH module); the TS module then calls the M1 Relay Agent (Go binary) over WebSocket (M1 infrastructure, downstream of JSON-RPC). Capability: `ssh.run_whitelisted_command` (live). Broker validates `command` against the 6-command subset (`uptime`, `df -h`, `free -m`, `systemctl status <svc>`, `journalctl -n <N>`, `systemctl list-units --type=service`) BEFORE dispatch (layer 1); Relay Agent `CheckCommand` validates at execution (layer 2, M1 G-004 contract).
- **Boundaries**: Never invokes non-whitelisted commands. Two-layer enforcement. Relay registration token stored via `SecretProvider.set` (INV-3).
- **Depends on**: `packages/mcp` (broker), `packages/secrets`, `packages/audit`, M1 Relay Agent (Go binary, WebSocket).

### packages/mcp/adapters/github (TypeScript — NEW in M2)
- **Description**: Read-only GitHub adapter. REST API client. Capabilities: `github.list_repos` (inventory, `GET /user/repos?per_page=100`), `github.get_recent_ci_runs` (live, `GET /repos/{owner}/{repo}/actions/runs`), `github.get_workflow_run` (live, `GET /repos/{owner}/{repo}/actions/runs/{run_id}`). Validates fine-grained PAT scopes at submit time: `metadata:read` + `actions:read` minimum (D-006). Observes `X-RateLimit-Remaining` header; backs off on 429.
- **Boundaries**: Calls only REST GET endpoints. Fine-grained PAT only (no classic PAT — coarse scopes grant write). Token stored via `SecretProvider.set` (INV-3).
- **Depends on**: `packages/mcp` (broker), `packages/secrets`, `packages/audit`.

### packages/mcp/adapters/gitea (TypeScript — NEW in M2)
- **Description**: Read-only Gitea adapter. REST API client. Capabilities: `gitea.list_repos` (inventory, `GET /user/repos?limit=50`), `gitea.get_recent_ci_runs` (live, `GET /repos/{owner}/{repo}/actions/runs`). Version-aware scope validation: Gitea ≥1.22 requires `read:repository`; Gitea <1.22 accepts any token with broker-side write-method blocklist (POST/PUT/DELETE/PATCH) as security backstop. Version detected via `GET /api/v1/version` and recorded in adapter config row.
- **Boundaries**: Calls only REST GET endpoints. Write-method blocklist enforced at broker for all versions. Token stored via `SecretProvider.set` (INV-3).
- **Depends on**: `packages/mcp` (broker), `packages/secrets`, `packages/audit`.

### packages/llm-mock (TypeScript — NEW in M2, devDependency, CI-only)
- **Description**: CI-only mock LLM provider for the M2 gate LLM smoke test. Implements OpenAI-compatible `/v1/chat/completions` that accepts a `tools` parameter (OpenAI tool definitions from the broker's `GET /api/mcp/tools`), returns `tool_calls` referencing one of the provided tools, accepts follow-up `tool` role messages (broker's translated adapter result), and synthesizes a grounded text response.
- **Boundaries**: `devDependency` only (not a production dependency). Import-guarded against prod bundle via build-time check/eslint rule. Consumed only by CI.
- **Depends on**: nothing (mock provider; the broker calls it as a BYOM endpoint).

### apps/control-plane (M2 additions)
- **M2 routes**: `GET /api/mcp/tools` (list tools, MCP `tools/list` facade), `POST /api/mcp/invoke` (invoke capability, returns `{correlationId, streamUrl}`), `GET /api/mcp/stream/:correlationId` (SSE stream), `POST /api/mcp/adapter` (configure adapter), `PATCH/DELETE /api/mcp/adapter/:id` (update/remove adapter). Settings → Adapters UI + Test-Call UI in the dashboard.
- **M2 schema**: `mcp_adapters` table (tenant_id, adapter_type, target_id, config JSON, secret_ref, validated, created_at) — tenant-scoped with RLS. No cache tables (in-memory only).
- **M2 audit events**: `adapter.configured`, `adapter.test_connection.{succeeded,failed}`, `adapter.capability_invoked`, `adapter.write_rejected` — all appended to M1's `audit_log` with hash-chain.

### M3 consumer contract (M2 spec §9 — frozen at M2 acceptance gate)

| Endpoint | Method | Purpose | M3 consumer |
|:---------|:-------|:--------|:------------|
| `/api/mcp/tools` | GET | List available tools (MCP `tools/list` facade) | M3 chat UI populates the LLM's `tools` parameter |
| `/api/mcp/invoke` | POST | Invoke a capability; returns `{correlationId, streamUrl}` | M3 chat orchestration calls when the LLM emits `tool_calls` |
| `/api/mcp/stream/:correlationId` | GET (SSE) | Stream tool execution output | M3 chat UI streams tool traces to the trace panel |
| `/api/mcp/adapter` | POST | Configure an adapter | M3 does not call (M2 Settings UI only) |
| `/api/mcp/adapter/:id` | PATCH/DELETE | Update/remove adapter config | M3 does not call (M2 Settings UI only) |

**Stability rules:** additive changes (new tools, adapters, SSE event types) permitted; breaking changes require M3 spec amendment + deprecation period.
**Open boundary (M3 design, not M2 build):** M3 needs a separate SSE endpoint for LLM token streaming (`/api/chat/stream` or similar) — distinct from MCP tool output streaming. M2's `/api/mcp/stream/:correlationId` streams tool execution output, not LLM completion tokens.

## Data Flow

### M1 happy path — Relay Agent registration (J2 steps 3–4)
```
Platform Lead ──install script──▶ customer Linux host
  detect-OS → install-binary → write-systemd-unit → register-target (writes tenant reg token to local config)
systemd ──start──▶ relay-agent (Go binary)
relay-agent ──outbound WebSocket (wss, tenant reg token)──▶ control-plane WS server
control-plane: auth token → resolve tenant (RLS) → INSERT target (hostname/OS/IP/version) → audit append
control-plane ──ack + target_id──▶ relay-agent
relay-agent ──heartbeat every Ns──▶ control-plane (updates last_seen → green status)
control-plane ──status fan-out──▶ dashboard (server-sent events / WS)
```

### M1 happy path — BYOM configure + validate (J2 step 2)
```
Admin ──POST /api/byom (url, key)──▶ API gateway
  auth → tenant resolve (RLS) → RBAC (Admin only) → audit append (config event)
  secrets.put(tenantId, "byom", key) → returns ref
  INSERT byom_endpoints (tenant_id, url, secret_ref) — under RLS
  BYOM validator: fetch OpenAI-compatible /v1/chat/completions with a trivial test prompt
    on success → mark validated=true, audit append (validation ok), return green
    on failure → rollback insert, audit append (validation fail), return error details (Edge 11)
```

### M3 (forward reference) — chat diagnostic (J1)
```
Operator ──prompt──▶ API gateway → auth → tenant → RBAC (Operator) → audit append (prompt)
  orchestrator (Trigger.dev task) → BYOM routing shim → POST tenant's BYOM /v1/chat/completions
    if unconfigured/unreachable → reject (REQ-009, Edge 1), audit append, halt
  LLM returns tool selection → MCP gateway → route to adapter (M2) → Relay Agent (SSH, M2)
    read-only enforced at gateway (403 on write) and Relay Agent (whitelist)
  tool output streams via SSE → UI trace panel → audit append (tool call + SSH command + output)
  LLM synthesizes cited answer → stream to UI → audit append (response)
  conversation persisted (tenant-scoped) → audit append
```

### M2 happy path — adapter configure + test connection (J1)
```
Sam ──POST /api/mcp/adapter (type=proxmox, host, token)──▶ API gateway
  auth → tenant resolve (RLS) → RBAC (Admin only) → audit append (adapter.configured)
  broker validates PVEAuditor role on target (REQ-025)
    if role missing → HTTP 422, no persist, audit append (validation fail)
  secrets.set(tenantId, "proxmox:<targetId>", token) → returns ref
  INSERT mcp_adapters (tenant_id, type, target_id, config, secret_ref, validated) — under RLS
  UI confirms save
Sam ──clicks "Test connection"──▶ broker invokes test_connection (REQ-016)
  broker: write-method blocklist check (GET only for Proxmox) → rate limit check → route to adapter
  adapter: GET /api2/json/nodes (PVE API, cookie auth) → 200 OK
  broker: audit append (adapter.test_connection.succeeded) → UI green
```

### M2 happy path — capability invocation via Test-Call UI (J2)
```
Sam/Devon ──POST /api/mcp/invoke (tool=github.list_repos, target_id, args={})──▶ API gateway
  auth → tenant resolve (RLS) → RBAC → audit append (adapter.capability_invoked, correlation_id=ULID)
  broker: write-method blocklist check (GET only) → rate limit check (60/min user, 300/min tenant)
    if rate exceeded → HTTP 429 + Retry-After, no adapter call
  broker: resolve adapter (tenant_id, github, target_id) → route (REQ-016)
  broker → returns {correlationId, streamUrl} to UI
UI ──GET /api/mcp/stream/:correlationId (SSE)──▶ broker
  broker: invoke adapter (in-process custom MCP transport, tools/call JSON-RPC)
  adapter: secrets.get(tenantId, "github:<targetId>") → PAT
  adapter: GET /user/repos?per_page=100 (GitHub REST, fine-grained PAT, metadata:read+actions:read)
    if 429 → back off (X-RateLimit-Remaining observed)
    if 403 → scope violation, HTTP 403 + audit append (adapter.write_rejected)
  adapter: normalize response → return to broker
  broker: emit SSE events (id=<ulid>-<seq>, event=tool_result, data={content:[...],isError:false})
  broker: terminal event (event=done) → close stream
  broker: audit append (adapter.capability_invoked, result=success)
UI: render result (inventory call → "cached Xs ago" if served from 60s TTL cache)
```

### M2 edge — SSH whitelist violation (Edge 7, defense-in-depth)
```
Sam ──POST /api/mcp/invoke (tool=ssh.run_whitelisted_command, args={command:"rm -rf /"})──▶ broker
  broker: validate command against 6-command subset (layer 1)
    "rm" not in {uptime, df, free, systemctl, journalctl} → REJECT at broker
  broker: HTTP 403 + audit append (adapter.write_rejected) → never invokes adapter
  (if broker somehow passed it: Relay Agent CheckCommand (layer 2) would also reject — defense-in-depth)
```

### M2 edge — SSE client disconnect (Edge 8)
```
Client ──GET /api/mcp/stream/:correlationId──▶ broker (SSE stream open)
Client disconnects mid-stream
  broker: detect EventSource close → cancel in-flight adapter call
  broker: clean up correlation context → no orphan adapter calls
  broker: NO audit event for client-side cancellation (per spec Edge 8)
```

## Build Order (M1 waves — each a vertical slice, testable + shippable)

1. **Wave A — Foundations.** Monorepo (pnpm): `apps/control-plane`, `apps/relay-agent` (Go module), `apps/dashboard`, `packages/{db,auth,audit,secrets,config}`. Postgres schema + RLS + `withTenant`. `audit_log` hash-chain + REVOKE UPDATE/DELETE. `SecretProvider` interface + AWS SM impl + local-encrypted impl. Trigger.dev bootstrap (runtime wired, no tasks yet). Covers REQ-038, REQ-039, REQ-040.
2. **Wave B — Identity & RBAC.** WorkOS SSO; session; tenant resolution middleware (`SET app.tenant_id`); RBAC at API gateway (Admin/Operator/Viewer → route permission map). First endpoint protected on day one. Covers REQ-001, REQ-002, REQ-003, REQ-004, REQ-005.
3. **Wave C — BYOM.** Tenant-scoped BYOM endpoint registry (URL in DB, key in secret manager); validate-on-save test inference call (OpenAI-compatible); routing shim (no inference in M1 — proxy contract + REQ-009 reject path). Covers REQ-006, REQ-007, REQ-008, REQ-009.
4. **Wave D — Relay Agent.** Modular install script (detect-OS/install-binary/write-systemd-unit/register-target; clean abort on unsupported OS). Go binary: outbound wss + tenant reg token, registration (tenant/target/hostname/OS/IP/version), heartbeat + exp-backoff (max 5 → alert), auto-reconnect, systemd unit w/ auto-restart. SSH whitelist file format + enforcement hook (no adapter yet — M2 plugs in). Covers REQ-010, REQ-011, REQ-012, REQ-013, (REQ-026 whitelist hook).
5. **Wave E — Dashboard surfacing.** WebSocket fan-out of agent status to dashboard; green/yellow/red; target hostname; last 100 log lines; per-tenant view under RLS. M1 gate demo: SSO → BYOM green → install → register → green dashboard. Covers REQ-014.

## Build Order (M2 waves — each a vertical slice, testable + shippable)

M2 ships on the v0.1.x patch line (M1's previous minor). Phase 0 seeds `v0.1.0`; each execution phase ships a progressive patch; the final phase's patch IS the M2 milestone release.

**Wave 0 — Prerequisites (not a spec REQ; must complete before any M2 adapter work):** CI Postgres 16 container with RLS verification (replaces PGlite-only verification); real GitHub PAT available in CI (ephemeral or test-org-scoped). Retroactively validates M1's RLS claims.

0. **Phase 0 — pre-execution.** SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL → MVP/UX. Ships `v0.1.0`.
1. **Wave F — MCP Gateway core.** `packages/mcp` broker: closed tool registry (9 tools), adapter router, write-method blocklist enforcer (INV-7 at broker), token-bucket rate limiter, SSE stream manager, OpenAI ↔ MCP translator, in-process custom transport. `mcp_adapters` table with RLS. Covers REQ-015, REQ-016, REQ-017, REQ-018, REQ-019, REQ-024.
2. **Wave G — Proxmox adapter.** `packages/mcp/adapters/proxmox`: PVE API client, `PVEAuditor` role validation (REQ-025), 3 capabilities (`list_vms`, `get_vm_status`, `get_node_metrics`). Covers REQ-020, REQ-025.
3. **Wave H — SSH/Linux adapter (Relay Agent).** `packages/mcp/adapters/ssh`: broker SSH whitelist validation (layer 1), downstream WebSocket to M1 Relay Agent, `ssh.run_whitelisted_command` capability. Reactivates go-engineer persona for Relay Agent integration. Covers REQ-021, REQ-026 (full — M1 shipped the hook; M2 plugs the adapter in).
4. **Wave I — Git adapters.** `packages/mcp/adapters/github` + `packages/mcp/adapters/gitea`: REST API clients, fine-grained PAT scope validation (D-006 for GitHub, version-aware for Gitea), 5 capabilities. Covers REQ-022, REQ-023, REQ-027.
5. **Wave J — SSE integration + LLM smoke + adapter UI.** `packages/llm-mock` (CI-only devDependency), LLM smoke test (OpenAI→MCP→adapter→result→synthesis against real GitHub), Settings → Adapters UI + Test-Call UI. Covers REQ-017 integration, M2 gate item 8 (LLM smoke).
6. **Final — Review + Audit + Ship.** Multi-persona review, project health audit, milestone ship v0.1.(N+1) = milestone release, merge to main. Covers all M2 (sign-off).

**Wave ordering & parallelism:** F must complete first (all adapters depend on the broker). G, H, I can run in parallel after F (different adapter territories; no cross-dependencies). J depends on F + at least one adapter (for the LLM smoke against GitHub). Final depends on all.