From 0359bd96824eab21a362ac1d51e47ca92bb98ff1 Mon Sep 17 00:00:00 2001 From: th-kim0823 Date: Sun, 10 May 2026 17:40:47 +0900 Subject: [PATCH] spec(fb-38): score semantics design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - search_hit.v1 에 optional score_kind 필드 (rrf | bm25 | cosine) - LexicalRetriever → Bm25, VectorRetriever → Cosine, HybridRetriever → Rrf - fb-37 search_with_trace 의 mode-dispatch hits 는 underlying retriever 의 score_kind 그대로 보존 - README + design §4 + SKILL 에 RRF 수식 전체 + "ranking signal, NOT confidence" 안내, agent 용 trust threshold 는 nested retrieval.{lexical,vector}_score - additive minor wire — schema bump 없음 Co-Authored-By: Claude Opus 4.7 (1M context) --- ...6-05-10-p9-fb-38-score-semantics-design.md | 173 ++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-10-p9-fb-38-score-semantics-design.md diff --git a/docs/superpowers/specs/2026-05-10-p9-fb-38-score-semantics-design.md b/docs/superpowers/specs/2026-05-10-p9-fb-38-score-semantics-design.md new file mode 100644 index 0000000..b4d4726 --- /dev/null +++ b/docs/superpowers/specs/2026-05-10-p9-fb-38-score-semantics-design.md @@ -0,0 +1,173 @@ +--- +title: "p9-fb-38 — Score semantics design" +phase: P9 +component: kebab-core + kebab-search + kebab-cli + wire-schema + docs +task_id: p9-fb-38 +status: design +target_version: 0.6.0 +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search, §10 UX, wire-schema search_hit.v1] +date: 2026-05-10 +--- + +# p9-fb-38 — Score semantics + +## Goal + +agent / 외부 통합이 `search_hit.v1.score` 를 confidence 로 오해하지 않도록 의미를 wire + docs 에 명시. 두 axes: + +- **Wire (additive minor)**: `search_hit.v1` 에 `score_kind: string` 필드 추가 — `"rrf"` (hybrid) / `"bm25"` (lexical) / `"cosine"` (vector). top-level `score` 의 의미를 hit 단위로 declarative 하게 표시. +- **Docs**: README + design §4 + SKILL 에 RRF 수식 전체 (`2/(k+rank)` per-chunk, `2/(k+1)` ceiling, normalize 과정) + "ranking signal, NOT confidence" 안내. agent 용 trust threshold 는 nested `retrieval.lexical_score` / `vector_score` 권장. + +wire change additive minor — schema bump 없음, 기존 consumer 무영향. + +## Behavior contract + +### Wire shape + +**`search_hit.v1`** — 신규 optional 필드: + +```jsonc +{ + "schema_version": "search_hit.v1", + "rank": 1, + "score": 0.5, // 기존 — RRF normalized (hybrid) 또는 raw (lexical / vector) + "score_kind": "rrf", // p9-fb-38 신규 — "rrf" | "bm25" | "cosine" + // 기존 필드 ... + "retrieval": { + "method": "hybrid", + "fusion_score": 0.5, + "lexical_score": 12.34, // BM25 raw — agent 용 trust threshold + "vector_score": 0.78, // cosine sim — agent 용 trust threshold + "lexical_rank": 1, + "vector_rank": 1 + } +} +``` + +`score_kind` `#[serde(default)]` (옛 reader / 옛 writer 호환). schema 의 `required` 미추가. + +### Score kind dispatch + +| Retriever | `score_kind` | top-level `score` 의 값 | +|-----------|--------------|--------------------------| +| LexicalRetriever | `"bm25"` | raw BM25 (≥ 0, unbounded) | +| VectorRetriever | `"cosine"` | cosine similarity (`[-1, 1]`) | +| HybridRetriever (fuse) | `"rrf"` | RRF normalized (`[0, 1]`) | +| HybridRetriever (search_with_trace, mode=Lexical) | `"bm25"` | pass-through from LexicalRetriever | +| HybridRetriever (search_with_trace, mode=Vector) | `"cosine"` | pass-through from VectorRetriever | + +`SearchMode` 와 `score_kind` 의 1:1 매핑은 hybrid retriever 가 mode-dispatch 시 결정. lexical/vector mode 의 hits 는 retriever 자체가 정한 kind 그대로. + +### Backwards-compat + +- 옛 wire reader (fb-38 이전 binary): JSON 에 `score_kind` 키 없음. ignore. 영향 없음. +- 옛 wire writer (fb-38 이전 binary 가 보낸 JSON 을 새 binary 가 읽음): `score_kind` 부재 → `default_score_kind() = ScoreKind::Rrf`. 잘못된 추정 가능 (실제 lexical / vector mode 였을 수도). +- 정확한 의미 보장은 v0.6.0 이후 binary 로 통일 시점부터. + +## Allowed / forbidden dependencies + +- `kebab-core`: 신규 dep 없음. enum + field 추가만. +- `kebab-search`: 신규 dep 없음. hit construction 시 score_kind 라벨링. +- `kebab-cli`: 무수정 (serde 자동 emit). +- `kebab-mcp`: 무수정 (`SearchHit` 직접 serialize → 자동 포함). +- `kebab-tui`: 무수정. + +`kebab-core` 의 다른 `kebab-*` 의존 금지 룰 그대로. + +## Public surface delta + +### kebab-core (`search.rs`) + +```rust +/// p9-fb-38: top-level `SearchHit.score` 의 의미 declaration. +/// `Rrf` (hybrid) / `Bm25` (lexical-only) / `Cosine` (vector-only). +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum ScoreKind { + Rrf, + Bm25, + Cosine, +} + +impl Default for ScoreKind { + fn default() -> Self { ScoreKind::Rrf } +} +``` + +`SearchHit` 확장: + +```rust +pub struct SearchHit { + // 기존 필드 ... + /// p9-fb-38: top-level `score` 의 의미 declaration. + /// 옛 wire (부재) → `Rrf` default (hybrid 가 기본 mode). + #[serde(default)] + pub score_kind: ScoreKind, +} +``` + +### kebab-search (lexical / vector / hybrid) + +- LexicalRetriever hit construction 에 `score_kind: ScoreKind::Bm25`. +- VectorRetriever hit construction 에 `score_kind: ScoreKind::Cosine`. +- HybridRetriever fuse 결과 hit 에 `score_kind: ScoreKind::Rrf`. +- HybridRetriever `search_with_trace` (fb-37) 의 Lexical/Vector branch 는 underlying retriever 의 hit 그대로 반환 — score_kind 는 그 retriever 의 라벨 (Bm25 / Cosine). + +### kebab-cli + kebab-mcp + +무수정. `serde_json::to_value(&hit)` 가 `score_kind` 를 자동 emit. + +## Test plan + +| kind | description | +|------|-------------| +| unit (kebab-core) | `ScoreKind` serde — Rrf↔"rrf", Bm25↔"bm25", Cosine↔"cosine" | +| unit (kebab-core) | `SearchHit` deserialization 시 `score_kind` 부재 → `Rrf` default | +| unit (kebab-core) | `ScoreKind::default() == Rrf` | +| unit (kebab-search/lexical) | LexicalRetriever hit 의 `score_kind == Bm25` | +| unit (kebab-search/vector) | VectorRetriever hit 의 `score_kind == Cosine` | +| unit (kebab-search/hybrid) | HybridRetriever fuse → all hits `Rrf` | +| unit (kebab-search/hybrid) | search_with_trace mode=Lexical → hits `Bm25` | +| 통합 (kebab-cli) | `kebab search Q --mode lexical --json` → `hits[0].score_kind == "bm25"` | +| 통합 (kebab-cli) | `kebab search Q --json` (default hybrid) → `hits[0].score_kind == "rrf"` | + +vector mode 통합 테스트는 embeddings 의존 — unit (search_with_trace mode=Vector 시 hits Cosine) 으로 대체. + +## Implementation steps (high-level) + +1. `kebab-core::ScoreKind` enum + `SearchHit.score_kind` field + 단위 테스트. +2. `kebab-search/lexical.rs` LexicalRetriever hit construction 에 `Bm25` 라벨 + 단위 테스트. +3. `kebab-search/vector.rs` VectorRetriever hit construction 에 `Cosine` + 단위 테스트. +4. `kebab-search/hybrid.rs` fuse + search_with_trace 에 `Rrf` / pass-through + 단위 테스트. +5. `kebab-cli` 통합 테스트 (lexical-only + hybrid). +6. `docs/wire-schema/v1/search_hit.schema.json` — `score_kind` 필드 추가. +7. README — "Score interpretation" 섹션 (RRF 수식 + score_kind 표 + agent guidance). +8. design §4 search — RRF 수식 + normalize 정의 + score_kind 필드 등록. +9. SKILL.md — `mcp__kebab__search` 응답에 `score_kind` 안내. +10. tasks/INDEX.md / spec status flip. + +## Risks / notes + +- **RRF normalizer 변경 시**: k_rrf default 변경 또는 retriever 수 > 2 확장 시 ceiling 재계산. design §4 RRF 수식 + README Score interpretation 갱신 필요. +- **vector mode 통합 테스트 부재**: 통합 테스트 fixture 가 embeddings 없음 (`provider = "none"`). 통합은 lexical / hybrid 만, vector 는 단위 테스트로 cover. +- **fb-37 search_with_trace 와 정합성**: search_with_trace 는 underlying retriever 가 만든 hit 을 그대로 trace 의 lex/vec list 에 채움 — score_kind 도 자동 보존. 추가 작업 없음. +- **`#[serde(default)]` 의미**: 옛 wire reader 가 `score_kind` 키 발견 시 unknown field 거절 안 함 (serde 기본 동작 — `deny_unknown_fields` 없음, 확인 완료). 안전. + +## Out of scope + +- top-level `score` rename 또는 deprecation (v0.7.0+ 검토). +- channel score 의 추가 노출 (이미 `retrieval` block 에 있음). +- score gate threshold 변경 (config.rag.score_gate). +- TUI score badge / color hint. +- per-channel score normalization (BM25/cosine 둘 다 raw 유지). +- `RetrievalDetail.method` 와 `score_kind` 의 정합성 검증 (둘 다 같은 정보 source 지만 별도 declarative). + +## Documentation updates (implementation PR 동시) + +- `README.md` — "Score interpretation" 섹션 (RRF 수식 + score_kind 표 + agent guidance). +- `docs/superpowers/specs/2026-04-27-kebab-final-form-design.md` §4 — RRF 수식 block + score_kind field 등록. +- `docs/wire-schema/v1/search_hit.schema.json` — `score_kind` enum 필드. +- `integrations/claude-code/kebab/SKILL.md` — `mcp__kebab__search` 응답 안내 (score_kind + "ranking signal, NOT confidence" + raw threshold guidance). +- `tasks/p9/p9-fb-38-score-semantics.md` — `status: open → completed`, design + plan 링크. +- `tasks/INDEX.md` — fb-38 행 ✅.