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:
2026-08-08 14:33:27 -05:00
parent 7fdde56560
commit 06917d43e2
13 changed files with 556 additions and 0 deletions

View File

@@ -0,0 +1,28 @@
# ADR-0011: Pattern-example RAG gated behind a validation spike
**Status:** Accepted (2026-08-08)
## Context
The pattern-example RAG pipeline — clone, chunk, embed, tag, search, refresh — is the largest
single body of work in the design doc, and it rests on an unvalidated hypothesis: that semantically
retrieved chunks from an example repository measurably improve an agent's output. Naive chunking
of source code is known to produce poor retrieval, so doing it well requires AST-aware chunking via
tree-sitter, which is most of the cost.
## Decision
Insert **phase 5.5, a throwaway spike**, before committing to phase 6. Index one real example repo
with naive chunking, run roughly ten realistic queries, and judge whether the retrieved chunks
would actually have improved an agent's output. The spike code is discarded regardless of outcome.
Phase 6 proceeds only if the spike passes. Its deliverable is a written go/no-go recommendation
with the queries and retrieved chunks as evidence.
## Consequences
- A large speculative build is de-risked for a few days of throwaway work.
- If the spike fails, the `patterns:` section of the canonical document still exists — names,
descriptions, and repository URLs — just without indexed, searchable example code.
- If it passes, the spike's queries become the seed of phase 6's evaluation set.
- Phase 6's size estimate stays honest rather than being quietly discovered mid-build.