---
title: kebab v0.20.2 release notes (draft)
created: 2026-05-29
status: draft
release_trigger:
  - 사용자 도그푸딩 필요 (8-finding dogfood 라운드 완료)
  - RAG prompt_template_version default 변경 (rag-v2 → rag-v3 응답언어 매칭)
  - eval --config facade 패치 (검색 품질 eval dogfood KB 평가 enabler)
---

# kebab v0.20.2 — Ask 응답언어 자동 매칭 + 검색 품질 eval 인프라

v0.20.1 (한국어 형태소 검색, 2026-05-28) 후속 patch release. 도그푸딩 8-finding 라운드에서 발견·수정된 문서/스키마/UX 표면 정비 + `rag-v3` 응답언어 규칙 + eval `--config` facade 패치를 한 번에 묶어 cut.

---

## 핵심 변경

### 1. Ask 응답언어 자동 매칭 (rag-v3, Finding #1 + O-2)

**변경 사실**: `SYSTEM_PROMPT_RAG_V3` 신설. `rag-v2` 의 7규칙 위에 "답변 언어 = 질문 언어" 규칙 추가. config `[rag] prompt_template_version` 의 default 가 `"rag-v2"` → `"rag-v3"` 로 변경.

```bash
# v0.20.2 기본 동작
kebab ask "What is the tokenizer?"  # → 영어 답변
kebab ask "토크나이저가 뭐야?"          # → 한국어 답변

# 이전 v3 고정하려면 (이미 default, 명시 생략 가능)
# [rag] prompt_template_version = "rag-v3"

# rag-v2 로 pin 하면 legacy 동작 (query 언어 무시)
# [rag] prompt_template_version = "rag-v2"
```

도그푸딩 확인: 영어 query → 영어 답변, 한국어 corpus 를 영어로 물으면 근거를 영어로 번역해 답함 (trade-off — 원문 보존이 필요하면 큰따옴표 직접 인용 규칙이 적용됨).

**trade-off**: 한국어 corpus 를 영어로 물을 때 LLM 이 근거를 영어로 번역해 답하므로 원문 표현이 일부 달라질 수 있다. 원문 그대로 필요하면 큰따옴표 직접 인용 (`[#번호]` 앞에 chunk 속 원문) 이 v3 에서도 유지된다.

**Finding O-2 — refusal 언어중립화**: rag-v3 system prompt 의 refusal/hedge 규칙에서 한국어 리터럴 (`근거가 부족하면 "근거가 부족하다"고 답한다`) 을 언어중립 표현 (`근거가 부족하면 답변 언어로 근거가 부족함을 밝히고 [#번호] 인용 없이 답한다`) 으로 변경.

**Known limitation**: gemma4:e4b 같은 소형 모델은 refusal 메시지의 언어가 query 언어와 불일치할 수 있음 (영어 query → 한국어 refusal 가능). refusal 판정 자체는 답변의 citation marker (`[#번호]`) 유무 기반 — 유효 marker 가 없으면 `LlmSelfJudge` 로 refuse 판정 — 이라 문구 언어와 무관하게 정확함 (refusal 문구 텍스트는 판정에 쓰이지 않음).

**mitigation**: 
- refusal 판정은 LLM 출력 내 marker 기반으로 항상 정상 동작.
- 언어 불일치가 허용 불가한 경우 `"rag-v2"` 로 pin (이전 동작 보존).
- 소형 모델 대신 gemma4:26b 등 대형 모델은 불일치 빈도가 현저히 낮음.

**upgrade 절차**: 기존 config 에 `prompt_template_version` 미명시 시 자동으로 v3 적용. v2 를 명시적으로 유지하려면 `[rag] prompt_template_version = "rag-v2"` 추가.

---

### 2. Bulk search input schema 확정 (Finding #2)

**변경 사실**: `docs/wire-schema/v1/bulk_search_input.schema.json` 이 15필드 완전 명세로 확정. `query` 누락 시 error shape hint 가 error.v1.message 에 포함됨.

```bash
# query 필수, 나머지 optional (15필드 중 1필수 + 14선택)
printf '%s\n' \
  '{"query":"한국","mode":"lexical","k":3}' \
  '{"query":"tokenizer","mode":"hybrid"}' \
  '{}' \
  | kebab search --bulk --json
# 세 번째 줄 → error.v1 (code: invalid_input, message 에 schema hint 포함)
```

**trade-off**: `query` 만 required, 나머지는 전부 optional + 스키마 검증은 agent 측 부담. error shape hint 로 agent 가 retry 없이 즉시 수정 가능.

**mitigation**: bulk cap 100 건 초과 시 즉시 `error.v1 (code: too_many_queries)` 반환.

**upgrade**: 기존 `{"query":"..."}` 형태는 완전 호환. 신규 optional 필드는 점진 추가 가능.

---

### 3. List docs human-readable path 보강 (Finding #3)

**변경 사실**: `kebab list docs` human-readable 출력이 `title \t doc_path` 에서 `doc_id \t title \t doc_path` 로 변경. title 중복(예: `README.md` + `README.md`) 시 doc_id 로 구분 가능.

```bash
kebab list docs
# 출력 예:
# abc123  README.md  /path/to/java/README.md
# def456  README.md  /path/to/kotlin/README.md
```

`--json` 출력 (`doc_summary.v1` array) 은 wire shape 변경 없음.

**trade-off**: human-readable 컬럼이 늘어나 좁은 터미널에서 wrap 가능. `--json` 으로 programmatic 처리 권장.

---

### 4. schema `index_version` 두 곳 구분 (Finding #7)

**변경 사실**: `schema.v1.models.index_version` 과 `search_hit.v1.index_version` 이 서로 다른 축임을 README 및 schema description 에 명시.

- `schema.v1.models.index_version` = **vector store (LanceDB)** version.
- `search_hit.v1.index_version` = **lexical (FTS5)** version.

cascade 에서 별도 추적 — 둘 중 하나가 변경돼도 나머지에 영향 없음.

**upgrade**: 기존 consumer 가 `index_version` 을 단일값으로 읽는 경우 fieldpath 확인 필요.

---

### 5. eval `--config` facade 패치 + 검색 품질 baseline 인프라

**변경 사실**: `kebab eval run / aggregate / compare` 가 `--config <path>` 를 honor. 이전에는 eval 이 XDG default config 만 읽어 dogfood KB (`/build/dogfood/config.toml`) 를 직접 평가할 수 없었음.

```bash
# v0.20.2: dogfood KB 에서 직접 eval
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
  kebab --config /build/dogfood/config.toml eval run --mode hybrid --k 10
```

**검색 품질 baseline** (v0.20.2, `/build/dogfood/golden_queries.yaml` 10 query):

| Mode | hit@1 | hit@3 | hit@10 | MRR | recall@10 | empty |
|------|-------|-------|--------|-----|-----------|-------|
| hybrid | 0.7 | **1.0** | 1.0 | **0.833** | 1.0 | 0 |
| lexical | 0.4 | 1.0 | 1.0 | 0.7 | 1.0 | 0 |

hybrid 가 vector 덕분에 top-1 정확도 우위. hit@3 이후는 두 모드 모두 완벽. 현재 ranking 조정 없이 달성 (`[[project_ranking_deferred]]` 결정 유효).

**golden 큐레이션 교훈**: 초기 dispatch.py 정답을 note 로만 한정한 것이 오류. eval 분해 시 vector 가 영어 docstring dispatch.py 를 top-1 으로 반환함을 발견, 정답에 추가 후 hit@3 0.9→1.0 개선. **교훈**: golden answer 는 "note 의 intent" 뿐 아니라 "합리적으로 관련된 모든 doc" 을 포함해야 함.

**trade-off**: `--config` 패치가 facade rule (kebab-cli → kebab-app `*_with_config`) 의 eval 적용. 누락 시 dogfood KB 와 XDG KB 의 결과가 섞여 eval 결과 오염.

**upgrade**: 기존 `kebab eval` 호출은 동작 변경 없음 (config 미명시 → XDG default 그대로).

---

### 6. 기타 docs/schema 정비 (Finding #4 · #5/#6 · #8)

**Finding #4 — doc.lang semantic 명시**: `lang = "und"` 는 소스코드 doc 의 정상 상태임을 README + schema description 에 명시. lingua 가 자연어 감지 대상 아님을 `lang_breakdown` 해석 가이드에 추가.

**Finding #5/#6 — fusion_score / score_kind**: `search_hit.v1` 의 `fusion_score` / `lexical_score` / `vector_score` / `lexical_rank` / `vector_rank` 가 모두 `retrieval` object 내부에 있음 (top-level 아님) 을 README 및 schema description 에 명시. 단일 mode (lexical/vector) 에서 `score == fusion_score == (lexical|vector)_score` 가 같은 값인 이유도 설명.

**Finding #8 — kebab init Ollama endpoint hint**: `kebab init` 이 생성하는 config.toml 에 `[models.llm] endpoint` 의 default 주석에 remote Ollama host 예시 추가.

---

## Version cascade 주의

| Version field | v0.20.1 | v0.20.2 |
|---|---|---|
| `prompt_template_version` default | `"rag-v2"` | **`"rag-v3"`** |
| wire schema shape | unchanged | unchanged (additive description only) |
| `eval config_snapshot_json` | `prompt_template_version: "rag-v2"` | `prompt_template_version: "rag-v3"` |

**eval compare 주의**: v0.20.1 eval run 과 v0.20.2 eval run 을 `eval compare` 할 때 `prompt_template_version` 이 다르므로 config_snapshot 이 다름. eval runner 가 snapshot 불일치를 경고하지 않으면 metric 변화의 원인이 rag 버전인지 corpus 변화인지 구분 불가. 정확한 비교는 `[rag] prompt_template_version = "rag-v2"` 로 pin 후 re-run.

---

## Breaking changes / 사용자 영향

- **prompt_template_version default 변경 (rag-v2 → rag-v3)**: 영어로 묻는 경우 영어로 답함. config 에 `prompt_template_version` 미명시한 사용자는 자동 적용. 이전 동작 유지는 `"rag-v2"` 명시.
- **소형 모델 refusal 언어 불일치 known limitation**: gemma4:e4b 사용자는 refusal 메시지 언어가 가끔 틀릴 수 있음. 정확도(판정)는 영향 없음.

---

## Upgrade 절차

```bash
# 1. binary 교체
git fetch && git checkout v0.20.2
cargo build --release -p kebab-cli -j 4

# 2. rag-v3 동작 확인
kebab ask "What is the tokenizer?" --hide-citations  # 영어 응답 기대
kebab ask "토크나이저가 뭐야?" --hide-citations        # 한국어 응답 기대

# 3. eval baseline 측정 (선택)
KEBAB_EVAL_GOLDEN=/build/dogfood/golden_queries.yaml \
  kebab --config /build/dogfood/config.toml eval run --mode hybrid --k 10
```

---

## References

- HOTFIXES entry: [`tasks/HOTFIXES.md`](../../tasks/HOTFIXES.md) 2026-05-29
- DOGFOOD scenarios: [`docs/DOGFOOD.md`](../DOGFOOD.md) §3.6 + §10.2
- eval `--config` facade: CLAUDE.md "The facade rule"
- Golden queries: `/build/dogfood/golden_queries.yaml`
- Eval logs: `/build/dogfood/logs/eval-{hybrid,lexical}-v0.20.2.json`