wtclaude
06917d43e2
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
1.4 KiB
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.