docs: add phased implementation plan and architecture decision records
Turns the design doc into an ordered, dependency-correct build plan (phases 0-9) with an exit criterion per phase, and records the twelve architectural decisions it rests on as ADRs. Decisions: single Rust binary with routed compose services; Streamable HTTP only; per-agent bearer tokens with clientInfo as a display hint only; SQLite; get_rules delivered via session gating; full-document rule delivery; project_id from day one; enforcement tier scoped to Bridle-mediated actions; stable tool list on upstream failure; OpenAI-compatible embeddings with model/dim guarding; pattern RAG gated behind a spike; CLAUDE.md + AGENTS.md as v1 renderer targets. Deviates from the design doc's original 1-8 ordering by moving the audit log and multi-project schema into phase 1, building the admin API incrementally rather than all at the Web Panel phase, downgrading vendor guardrail sourcing to manual-first, and gating the pattern-example RAG behind a validation spike. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m
This commit is contained in:
24
docs/adr/0002-streamable-http-only.md
Normal file
24
docs/adr/0002-streamable-http-only.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# ADR-0002: Streamable HTTP as the sole MCP transport
|
||||
|
||||
**Status:** Accepted (2026-08-08)
|
||||
|
||||
## Context
|
||||
|
||||
MCP defines stdio and Streamable HTTP transports; an older HTTP+SSE transport is deprecated in
|
||||
favor of Streamable HTTP. Bridle is a networked gateway intended to be reachable from agents over
|
||||
WireGuard, which rules out stdio as the primary transport. A local stdio shim bridging to the HTTP
|
||||
endpoint was considered for clients with weak Streamable HTTP support, as was continuing to serve
|
||||
the deprecated SSE transport.
|
||||
|
||||
## Decision
|
||||
|
||||
Serve **Streamable HTTP only**, at `/mcp`. No stdio shim and no deprecated SSE endpoint at v1.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Matches the per-agent bearer token model (ADR-0003) directly — the token rides the
|
||||
`Authorization` header.
|
||||
- Works over WireGuard without extra components.
|
||||
- One transport to implement, test, and secure.
|
||||
- If a target agent turns out to have unusable Streamable HTTP support, a `bridle-stdio` bridging
|
||||
binary is the fallback. It is not in scope until a specific agent demonstrably needs it.
|
||||
Reference in New Issue
Block a user