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:
29
docs/adr/0004-sqlite-datastore.md
Normal file
29
docs/adr/0004-sqlite-datastore.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# ADR-0004: SQLite as the primary datastore
|
||||
|
||||
**Status:** Accepted (2026-08-08)
|
||||
|
||||
## Context
|
||||
|
||||
The design doc specified no storage backend for the canonical rules document, permissions, audit
|
||||
log, sessions, secret metadata, or the approval queue. Options considered were SQLite, a bundled
|
||||
Postgres, and git-backed YAML in a Gitea repository with a database for everything else.
|
||||
|
||||
The git-backed option was genuinely attractive in a Gitea shop — free versioning, diffs, and
|
||||
PR-based review of guardrail changes. It was rejected because Web Panel edits and direct git edits
|
||||
create two write paths to the same canonical data that must then be reconciled.
|
||||
|
||||
## Decision
|
||||
|
||||
**SQLite**, one file (`bridle.db`), holding `projects`, `agents`, `tokens`, `permissions`,
|
||||
`audit_log`, `rules_documents` (JSON plus `schema_version`), `guardrails` with provenance, and
|
||||
`approval_queue`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Zero operational overhead; backup is copying one file.
|
||||
- Correct default for the single-host, single-user target.
|
||||
- Rules versioning must be built explicitly (document history in-table) rather than inherited from
|
||||
git.
|
||||
- Migration to Postgres remains straightforward if multi-host or a multi-user panel ever
|
||||
materializes. Keep SQL portable and avoid SQLite-specific constructs where a standard equivalent
|
||||
exists.
|
||||
Reference in New Issue
Block a user