kebab/docs/release-notes/v0.29.0-draft.md

title, created, status, release_trigger

title	created	status	release_trigger
kebab v0.29.0 release notes (draft)	2026-06-21	draft	신규 CLI flag `kebab search --source` / `--source-type` — pre-1.0 minor bump 신규 config `workspace.sources` + V014 migration (documents.source_id) — 인터페이스 추가 config schema v3→v4 (단일 root → implicit default source 미러)

kebab v0.29.0 — provenance 출처 필터: 멀티소스 + --source

v0.28.0(config 스키마 재편) 후속 minor release. 혼합 출처 KB — 예컨대 위키 문서와 jira 이슈를 한 KB 에 같이 넣은 경우 — 에서 색인은 전부 하되 질의 시 출처로 좁히는 provenance 레버를 추가한다. 기존 단일-폴더 사용자는 아무것도 손대지 않아도 된다 — 단일 workspace.root 는 자동으로 default 라는 하나의 source 로 정규화되고, 새 DB 컬럼은 기존 문서에 default 를 자동 채우는 additive 마이그레이션이라 재색인이 발생하지 않는다.

---

변경 사실

1) 검색 출처 필터 2종. kebab search 에 두 필터가 생겼다.

flag	의미
--source <id>	[[workspace.sources]] 에 선언한 source 의 id 로 필터 (예: --source jira)
--source-type <type>	markdown / note / paper / reference / inbox 로 필터

둘 다 반복(--source a --source b) 또는 콤마(--source a,b)로 여러 값을 줄 수 있고 OR 로 묶인다. 빈 값 = 무필터. lexical · vector · hybrid 모든 검색 모드에 동일하게 적용된다(직접 인덱스 컬럼 — 추가 비용 거의 없음).

2) [[workspace.sources]] 멀티소스 config. 단일 [workspace] root 대신 여러 폴더를 명명 source 로 선언할 수 있다.

[[workspace.sources]]
id = "notes"
root = "~/KnowledgeBase/notes"

[[workspace.sources]]
id = "jira"
root = "~/exports/jira"
trust_level = "secondary"   # frontmatter 가 없을 때의 출처 기본 신뢰도
source_type = "reference"   # frontmatter 가 없을 때의 출처 기본 타입

각 source 의 id 는 그 폴더에서 색인된 모든 문서에 stamp 되고 (documents.source_id 컬럼), --source <id> 필터의 대상이 된다. trust_level / source_type 은 출처 기본값으로, 문서 frontmatter 가 해당 필드를 지정하지 않을 때만 적용된다 (우선순위: frontmatter > source 기본값 > 하드코딩 Primary/Markdown). kebab ingest 는 --root 를 주지 않으면 선언된 모든 source 를 각자의 root + exclude 로 순회한다.

Trade-off — 왜 필터인가 (전역 trust 가중은 반증됨)

"출처가 섞이면 신뢰도로 가중하면 되지 않나?" 를 통제 실험으로 검증했고, 전역 trust 곱셈가중은 반증됐다. jira 를 docs KB 에 섞으면 개념 질의는 약하게 오염(top-3 정답은 유지, rank1→2 강등)되지만 운영/이슈 질의는 크게 개선된다 (jira_only hit@10 0/10 → 10/10). 그런데 jira 점수에 θ=0.85 만 곱해도 RAG 점수 압축 때문에 incident MRR 이 0.918→0.340 으로 절벽 하락한다 — 작은 오염을 잡으려다 큰 개선을 버리는 see-saw. 그래서 전역 가중은 빌드하지 않았다.

올바른 레버는 질의 시 출처 필터링이다: 색인은 전부 해 두고(운영 질의는 jira 가 답하게), 개념 질의에서만 --source wiki 로 좁힌다. see-saw 없이 양쪽을 다 얻는다.

Mitigation — 기존 사용자 무영향 (재색인 0)

• 단일 root 그대로 동작: [[workspace.sources]] 를 선언하지 않으면 기존 workspace.root 가 implicit default source 로 정규화된다. 모든 문서가 source_id = "default".
• V014 는 additive: documents.source_id 컬럼은 DEFAULT 'default' 라 기존 row 가 자동으로 채워진다. 데이터 재작성·재색인·corpus_revision bump 없음.
• config v3→v4 자동 변환: load 시 메모리에서 자동 변환(디스크 미변경), kebab config migrate 로 파일 갱신 시 값·주석 보존 + 멱등. 단일 root 는 [[workspace.sources]] id=default 로 미러되며 기존 root 키도 그대로 남는다.

도그푸딩(v0.29.0 release 빌드, 실험 corpus): 620 문서 / 0 error 색인, source_id = {jira: 400, wiki: 220}. trust precedence 실측 — jira 는 source 기본값 secondary 라 --trust-min primary 시 0/6 노출, wiki 는 primary 유지. 출처 필터 실측 — --source wiki 로 개념 질의 MRR 0.780→0.810(오염 회복), --source jira 로 incident 0.918→0.975.

Upgrade 절차

1. 아무것도 안 해도 된다 — 기존 config.toml 과 KB 는 그대로 동작한다(단일 root = default source, V014 자동 backfill).
2. 출처를 나누고 싶으면 kebab config migrate 로 config 를 v4 로 갱신한 뒤 [[workspace.sources]] 블록을 손으로 추가하고 kebab ingest --force-reingest 로 각 문서에 새 source_id 를 stamp 한다. (단순 ingest 는 내용이 안 바뀐 문서를 skip 하므로, 기존 문서의 source_id 를 default 외 값으로 바꾸려면 --force-reingest 필요.)
3. 검색에서 --source <id> / --source-type <type> 로 출처를 좁힌다.

Known limitations / 다음

• MCP search 도구는 아직 --source / --source-type 를 노출하지 않는다 (CLI 전용). agent 용 MCP 필터 노출은 다음 additive 후보.
• kebab list 출력(doc_summary.v1)에 source_id 가 아직 안 실린다.
• kebab ask citation 에 provenance 라벨이 아직 없다 — 검색 필터는 되지만 답변 근거의 출처 표기는 다음 단계.