From 9a81f9eaf771958361cf00da7d495019cd4c1699 Mon Sep 17 00:00:00 2001
From: Brummel <mould@mycelium.de>
Date: Sun, 31 May 2026 19:06:37 +0200
Subject: [PATCH] docs: plan for renaming Mode variants A/C (refs #2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 docs/plans/2026-05-31-rename-mode-variants.md | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/plans/2026-05-31-rename-mode-variants.md

diff --git a/docs/plans/2026-05-31-rename-mode-variants.md b/docs/plans/2026-05-31-rename-mode-variants.md
new file mode 100644
index 0000000..d63b7e2
--- /dev/null
+++ b/docs/plans/2026-05-31-rename-mode-variants.md
@@ -0,0 +1,74 @@
+# Plan — Rename Mode variants A/C to self-describing names (closes #2)
+
+## Context
+
+The retrieval-mode enum uses opaque single letters `Mode { C, A }`
+(src/model.rs). Neither the identifier nor the CLI token `--mode a`
+conveys intent. The letters trace the design ledger's three-stage axis
+(docs/specs/2026-05-18-…:60-63): **C** = lexical baseline (BM25 + tag
+filter, offline), **B** = generative rerank (reserved, NOT in scope,
+no enum variant), **A** = hybrid (lexical ∪ semantic → RRF → rerank).
+
+### Ratified decisions (resolved during this iteration)
+
+- `Mode::C → Mode::Lexical`, `Mode::A → Mode::Hybrid` (maps onto the
+  glossary one-line definitions).
+- CLI canonical tokens: `lexical` / `hybrid`. Keep `c` / `a` as
+  **accepted input aliases** (zero-cost backward compatibility; no
+  external consumer exists, but it protects typed-by-hand invocations).
+- Diagnostics `mode` string (`format!("{:?}", mode)` in src/pipeline.rs)
+  may change freely to `"Lexical"` / `"Hybrid"`: verified no downstream
+  consumer parses it. doctate is the future integrator and embeds the
+  **library** (the `Mode` enum), not the JSON string (spec §103).
+- The reserved generative tier keeps conceptual room: a future
+  `Mode::Generative` does not collide with `Lexical`/`Hybrid`.
+
+## Tasks (one cohesive rename — review as a unit)
+
+1. **Enum + parser** (src/model.rs)
+   - Rename variants `C → Lexical`, `A → Hybrid`.
+   - `FromStr`: canonical `"lexical"`/`"hybrid"`; keep `"c"`/`"a"` as
+     accepted aliases (case-insensitive, as today). Unknown → same error.
+
+2. **CLI** (src/bin/alpha_id.rs)
+   - `--mode` `default_value` `"c"` → `"lexical"` on both `Suggest` and
+     `Eval`.
+   - `eval --mode both` expansion `vec![Mode::C, Mode::A]` →
+     `vec![Mode::Lexical, Mode::Hybrid]`.
+
+3. **Pipeline** (src/pipeline.rs)
+   - Match arms `Mode::C`/`Mode::A` → `Mode::Lexical`/`Mode::Hybrid`.
+   - Rename private methods `collect_mode_c → collect_lexical`,
+     `collect_mode_a → collect_hybrid`, and update their doc comments and
+     the inline "Mode C/A" comments to the new names. (Leaving
+     `collect_mode_c` behind a `Mode::Lexical` arm would reintroduce the
+     exact opaqueness this issue removes.)
+
+4. **Tests**
+   - `git mv tests/pipeline_mode_c_tests.rs tests/pipeline_lexical_tests.rs`
+     and `…mode_a_tests.rs → …hybrid_tests.rs`; update `Mode::C`/`Mode::A`
+     and any `mode_c`/`mode_a` test-fn names inside to the new names.
+   - tests/model_tests.rs: update the parse assertions to the new
+     variants; add an assertion that the `c`/`a` aliases still parse
+     (to the new variants) so the alias contract is pinned.
+
+5. **Glossary** (docs/glossary.md) — record-reality update
+   - Headings `### Mode C` → `### Mode Lexical`, `### Mode A` →
+     `### Mode Hybrid`. Move the old letter forms into the **Avoid**
+     lines (`Mode C`, `Modus C`, `mode c`, etc.).
+   - Update the cross-references that name "Mode A"/"Mode C" in the RRF,
+     rerank, vector_index, and degrade entries.
+
+6. **Spec synopsis** (docs/specs/2026-05-18-…:200,202)
+   - `--mode c|a` → `--mode lexical|hybrid` on both synopsis lines.
+     In-place token edit only; the surrounding German prose is
+     pre-existing and out of scope to translate.
+
+## Acceptance
+
+- `cargo build` and `cargo test` green.
+- `alpha-id suggest --mode lexical` / `--mode hybrid` work; `--mode c` /
+  `--mode a` still accepted (alias); default is `lexical`.
+- No `Mode::C` / `Mode::A` / `collect_mode_[ca]` / `### Mode C|A`
+  references remain anywhere in src, tests, or docs (except as **Avoid**
+  synonyms in the glossary).