Design spec for the "versioned bundle" cycle binding issues #3 (pack the
per-file embedding store into one contiguous matrix file) and #4 (bind
{corpus snapshot, embed model, index} as one versioned artifact).
Ratified decisions (user-approved across the brainstorm):
- Approach 1: single self-describing file (magic + JSON-header manifest +
row-major f32 payload), loaded with one fs::read. No mmap (a brute-force
full-scan cosine index touches every row per query, so mmap yields no
runtime benefit and is rejected to avoid an unsafe dependency). VectorIndex
and the per-file store are untouched — the store stays the build/resume
path, the packed file is an additive serve-path artifact.
- Mismatch posture: loud but not fatal. A structurally wrong index (corpus
sha256 or embed_model disagreement) builds no VectorIndex and surfaces as a
distinct IndexStatus::Mismatch in diagnostics plus a load-time warning,
instead of silently degrading Mode Hybrid to Lexical. Mode Lexical, which
never needs the index, keeps serving.
- Two iterations, one format: iter 1 delivers the format + `index --pack` +
packed-first load; iter 2 enforces the manifest check and the observable
index_status surface.
grounding-check: PASS (7 load-bearing assumptions ratified by green tests).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The retrieval-mode enum used opaque single letters `Mode { C, A }`;
neither the identifier nor the operator-facing `--mode a` token
conveyed what the mode does. Rename to self-describing names that map
directly onto the glossary definitions:
Mode::C -> Mode::Lexical (BM25 + tag filter, offline, no IONOS)
Mode::A -> Mode::Hybrid (lexical u semantic -> RRF -> rerank)
Decisions taken (the issue's open questions, resolved):
- CLI canonical tokens are now `lexical` / `hybrid`; the default is
`lexical`. The legacy `c` / `a` tokens stay accepted as
case-insensitive input aliases (zero cost; protects hand-typed
invocations). A unit test pins the alias contract.
- The diagnostics `mode` string (Debug-derived) now emits
"Lexical"/"Hybrid". Verified safe: no downstream consumer parses it.
doctate is the future integrator and embeds the library (the `Mode`
enum), not the JSON string (design spec §103).
- The reserved, out-of-scope generative tier (spec's "Mode B") keeps
conceptual room: a future `Mode::Generative` does not collide with
the retrieval-strategy names Lexical/Hybrid.
Surface: enum + FromStr, CLI defaults and `eval --mode both`
expansion, the private `collect_mode_c`/`collect_mode_a` methods (now
`collect_lexical`/`collect_hybrid`) and their comments, the two
pipeline mode test files (renamed), the eval CLI test, the glossary
(old letter forms demoted to Avoid lists), and the spec CLI synopsis.
closes#2
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Records the ratified naming decisions (Lexical/Hybrid, c/a kept as
input aliases, diagnostics string free to change — no downstream
consumer) and the bite-sized rename task list for the implement step.
refs #2
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add .claude/dev-cycle-profile.yml (skills-plugin profile) with
paths.glossary pointing at the new docs/glossary.md, so the glossary
becomes standing reading for every role. The glossary pins 19 canonical
terms bootstrapped from the design spec and source doc comments;
canonical forms are English (repo-English rule), German spec-prose forms
listed under Avoid.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The superpowers workflow methodology is no longer in use. Move the
methodology-neutral design spec to docs/specs/ as the project's design
ledger, drop the superpowers-bound implementation plan (it referenced
superpowers sub-skills), and remove the now-dead /docs/superpowers/
.gitignore entry.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Source-string analysis showed the Hypertonie miss is not a bug but a
structural consequence of embedding whole noisy Anamnese paragraphs
against terse Alpha-ID corpus strings. Resolution (user-decided): the
caller (doctate's LLM) extracts diagnostic phrases; this project still
contains no LLM — it just receives a cleaner input contract.
Spec: new §1a (rationale + generous extraction contract + the honest
extractor-is-recall-bottleneck trade-off); §1/§2/§3/§6/§8/§9/status
updated; §6 reworks eval (representativeness shift, paraphrase axis,
hand-labeled phrase-list set, separated extraction-ceiling vs matcher
recall). Plan: Goal/Architecture, revision banner, Task 6 rewritten
(one non-empty line = one unit; split_segments name/fields retained,
minimal-churn decision), Task 11/19 revision notes.
Code not yet changed (segment.rs still blank-line splits) — next step.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents the corpus↔ClaML 5th-digit gap, the decided Modifier/
ModifierClass expansion fix (Goal 1), and the deterministic /
seeded-sample eval corrections from the final review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brainstormed design: free-text dictation (marker-segmented by
doctate) -> single prioritized top-10 ICD-10-GM list with tag
filtering. Two modes (C lexical baseline, A hybrid retrieval +
IONOS bge-m3 + Qwen3-VL-Reranker-8B), eval harness via synthetic
transcription errors, one-time cost-guarded embedding.
Licensed BfArM data dirs and local settings are gitignored.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brummel