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:
28
docs/adr/0011-pattern-rag-behind-spike.md
Normal file
28
docs/adr/0011-pattern-rag-behind-spike.md
Normal 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.
|
||||
Reference in New Issue
Block a user