목표 재정의: 한/영 overlap → 같은 의미의 다양한 표현(동의어·다른 어휘·풀어쓴
문장·한영)에서 일관된 답변 품질. 지난 reranker 실험이 overlap 프록시 최적화로
헛돈 교훈 반영 — 처방 전 진짜 지표(변형 일관성)를 직접 재는 평가부터.
Phase 1(본 spec 구현): kebab-eval golden suite에 변형 그룹(intent group) +
변형 일관성 메트릭(recall_spread, answer_consistency) + recall@pool vs recall@k로
(A)순위출렁/(B)어휘격차 자동 판별. Phase 2(처방)는 측정 결과 게이트 뒤 조건부.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CLAUDE.md docs-split 규칙에 따라 사용자 visible surface 변경 동기화.
README:
- [rag] prompt_template_version default rag-v2 → rag-v3 (v0.20.2)
- v3 규칙 설명 (답변 언어 = 질문 언어)
- O-2 known limitation (소형 모델 refusal 언어 불일치)
HANDOFF:
- 머지 후 발견된 버그/결정 에 v0.20.2 1줄 요약 추가
- 검색 품질 baseline (hybrid MRR=0.833) + O-2 known limitation 언급
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
v0.20.2 릴리즈 노트 초안 작성. 사용자 영향 4단락 구조로 각 finding 기술.
- Finding #1/O-2: rag-v3 응답언어 자동 매칭 + refusal 언어중립화
- Finding #2: bulk search input schema 확정 (15필드)
- Finding #3: list docs human-readable path 보강
- Finding #7: index_version 두 곳 구분 (vector vs FTS5)
- eval --config facade + 검색 품질 baseline (hybrid hit@3=1.0 / MRR=0.833)
- Finding #4/#5/#6/#8: docs/schema 정비
- version cascade 주의 (rag-v3 → eval compare)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
8-finding 도그푸딩 라운드 및 검색 품질 baseline 결과를 HOTFIXES 에 기록.
- 8 findings 요약 표 (rag-v3, bulk schema, list docs, index_version 등)
- Finding O-2 known limitation (소형 모델 refusal 언어 불일치)
- 검색 품질 baseline 표 (hybrid MRR=0.833, lexical MRR=0.7)
- golden 큐레이션 교훈 (dispatch.py 정답 정정 → hit@3 0.9→1.0)
- eval logs cross-link
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
eval --config facade 패치로 dogfood KB 직접 평가 가능해짐에 따라
§10 Eval 에 §10.2 검색 품질 baseline 섹션 추가.
- golden suite 실행 명령 (hybrid + lexical eval run → aggregate)
- v0.20.2 metric baseline 표 (hybrid hit@3=1.0 / MRR=0.833)
- 정성 체크리스트 (한국어 2자 hit@3, empty=0, MRR 임계치)
- golden 큐레이션 절차 + dispatch.py 오류 교훈
- §10.1 로 기존 basic eval run 재구성
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Incorporates all critic (opus) round-1 findings into the dogfood
search-quality eval design spec:
BLOCKER-1: §4.4 execution commands now use --config /build/dogfood/config.toml
(Task A facade-rule patch makes this the canonical path). §5.1 re-titled
from "(후속 패치)" to "Task A로 적용됨 — 권장 운영 경로"; XDG workarounds
demoted to "패치 전 fallback". Intro paragraph updated accordingly.
MAJOR-1: §3 Non-Goals gains an explicit bullet: lang/media/code_lang
SearchFilters validation is out of scope for this harness (runner uses
SearchFilters::default(), runner.rs:151). §4.1 "code 검색" row no longer
claims code_lang filter coverage.
MINOR-1: §4.3 step 3 now names kebab inspect doc <id> as the primary
chunk-selection path (breaks chunk-level curation loop); search hits
demoted to "보조 확인용".
MINOR-2: §4.1 golden category table gains two new rows — 한국어 N-gram
fallback query (복합어/신조어 coverage) and 영어 whole-token exact query
(separates substring artefacts).
MINOR-3: §4.1 YAML header note added: record corpus_revision in golden
file so stale-bail root cause is immediately traceable.
NIT: §9 References line numbers corrected (runner.rs:31, metrics.rs:116/144);
runner.rs:151 SearchFilters::default() reference added.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Cmd::Eval now loads Config via cli.config (same pattern as all other
subcommands) before dispatching to the inner match. Each arm now calls
the *_with_config variant:
run_eval(&opts) → run_eval_with_config(&cfg, &opts)
compute_aggregate(run_id) → compute_aggregate_with_config(&cfg, run_id)
store_aggregate(run_id, ..) → store_aggregate_with_config(&cfg, run_id, ..)
Compare already called compare_runs_with_config but sourced cfg from
Config::load(None) — that redundant load is removed; cfg comes from
the shared binding above.
Fixes the same facade-rule regression pattern as P3-5 / P4-3: previously
`kebab --config /build/dogfood/config.toml eval run` silently evaluated
the XDG-default (empty) KB instead of the dogfood KB.
Also fixes runner.rs test that hardcoded rag-v2 after commit 5719969
bumped the default prompt_template_version to rag-v3.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
line 899: V1만 legacy → V1/V2 둘 다 legacy, v0.20.2 부터 rag-v3 default 선언.
line 1349 (★): config 예시 default rag-v2 → rag-v3.
line 1533 (★): §9 cascade table 코드 상수 rag-v2 → rag-v3.
line 287 이후: answer.v1 예시 블록에 historical snapshot 주석 추가 (n1 — model+ptv stale, 값 변경 안 함).
task spec grep 판단: tasks/p9/p9-fb-15 의 rag-v2 언급 2줄은 rag-v2 도입 시점 historical 기술 → frozen 유지.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
schema.schema.json models.index_version: vector store (LanceDB) version 임을 명시.
search_hit.schema.json index_version: lexical (FTS5) version 임을 명시.
search_hit.schema.json retrieval: 내부 필드 목록 + hybrid 전용 fusion 설명 추가 (hunk 공유).
README kebab schema 행: index_version 두 곳의 의미가 다름을 주의 표기 추가.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
README Score 해석 절에 score ↔ retrieval.* 구조 설명 추가:
- fusion_score/lexical_score/vector_score/lexical_rank/vector_rank 는 retrieval 내부 (top-level 아님).
- single-mode 에서 score==fusion_score==lexical/vector_score 가 같은 값인 것은 정상 (Finding X).
search_hit.schema.json score 필드에 score_kind 관계 + single-mode 동일값 이유 설명 추가.
search_hit.schema.json retrieval/index_version 설명은 Task 12 커밋에 포함 (같은 hunk).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lang_breakdown description에 code 문서는 자연어 감지 미수행(lang="und" 정상) 사실 추가.
README에 lang vs code_lang 설명 절 신규 추가.
task spec grep: tasks/p9/p9-fb-15 의 rag-v2 언급은 historical 기술 → frozen 유지.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
SYSTEM_PROMPT_RAG_V3: 한국어 리터럴 refusal/hedge 문구를 언어 중립으로 교체.
- 근거가 부족하면 "근거가 부족하다"고 답한다. → 답변 언어로 근거가 부족함을 밝히고 [#번호] 인용 없이 답한다.
- 근거가 모호하면 "확실하지 않다" 라고 명시한다. → 근거가 모호하면 답변 언어로 불확실함을 명시한다.
MULTI_HOP_SYNTHESIZE_SYSTEM_PROMPT: 동일 패턴 두 곳 교체.
- 근거가 부족하면 "근거가 부족하다"고 답한다. → 답변 언어로 근거가 부족함을 밝히고 [#번호] 인용 없이 답한다.
- self-check 의 즉시 "근거가 부족하다" 라고만 답한다. → 즉시 답변 언어로 근거가 부족하다고만 답한다.
refusal 판정 로직(citation marker 기반)은 무변경 — 문구만 언어 중립화.
test rag_v3_contains_v2_rules_plus_language_rule: "확실하지 않다" assert → "불확실함" assert 로 갱신.
task spec grep: tasks/p9/p9-fb-15 의 rag-v2 언급은 도입 시점 historical 기술 → frozen 유지.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
planner(opus) 작성 → critic 리뷰 시도 → leader 좌표 검증.
8 todo → 15 task: 코드 4 (rag-v3 / list docs / bulk / init) + 각 finding 후
전체 도그푸딩 검증 task 4 + docs-only 3 + contract + HOTFIXES/release-notes + version bump.
plan critic round-1 은 환경 도구 손상으로 좌표 blocker(B-1/B-2/M-1/M-2)를 오진 →
leader 가 pipeline.rs/config/cli/bulk/Cargo.toml 을 직접 grep 검증해 plan 좌표 정확 확인,
executor 용 "anchor grep 재확인" + binary 경로 주의 헤더 추가.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
v0.20.1 전체 도그푸딩에서 발견된 8 todo (Ask 응답언어 rag-v3 / doc.lang
docs / bulk input / list title / fusion_score·score_kind / schema
index_version / Ollama hint) 를 단일 patch release 로 설계.
writer worker 초안 → opus critic round-1 리뷰 반영:
- B1: top-level score placeholder → 확정 (score_kind 가 의미 선언, search.rs:95-99)
- M1: 이미지 caption 언어 강제 out-of-scope 명시
- M2: config default 테스트(lib.rs:1316) 갱신 필요 명시
- M3: bulk input 전체 필드 (query/mode/k/trust_min/ingested_after/media/tag/lang)
- M4: rag-v3 의 eval_runs.config_snapshot_json cascade 영향
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
머지 후 v0.20.1 의 full dogfood (사용자 실제 corpus 6293 file, 3.5
시간 ingest, §1~§11 시나리오) 발견된 findings 를 새 session 의 self-
contained todo handoff 로 정리.
P0 (bug / 의도와 다른 동작):
- #1 Ask 영어 query → 한국어 응답 (rag-v2 prompt template 강제)
- #2 bulk search input format 불명확 (wire schema 미명시)
- #3 list docs title 중복 (heading-based, doc_path 보조 필요)
- #4 doc.lang = und 53% (code file 의 lang detection 실패)
P1 (docs drift):
- #5 fusion_score 위치 (.retrieval.fusion_score)
- #6 score_kind="bm25" 의미 (lexical mode 의 fusion_score)
- #7 schema index_version vs lexical_index_version 혼동
P2 (setup):
- #8 Ollama endpoint default 가 localhost (사용자 환경 remote)
각 todo 별 severity, scenario, suspected location, action item 명시.
새 session 시작 명령 + branch 권장 + 도그푸딩 재실행 절차 + finding
cumulative table 포함.
Repo state: main HEAD=a0c7fa3, clean. v0.20.1 binary OK. /build/dogfood/
KB (3940 docs, 34896 chunks) preserved for regression test.
사용자 정정 따라 dogfood data layout 갱신:
1. 위치: /build/cache/dogfood/ → /build/dogfood/. /build/cache 는 의미상
캐시 (regeneratable downloads/models) 이지 test data 아님.
/build/dogfood 는 sudo 로 신설 + chown.
2. 분류 정책: kebab version / 생성 시점 / scenario name prefix 금지
(v0.20.1-dogfood/, dogfood-v018/ 같은 디렉토리 신설 X). 모든 분류
는 문서 의미 / 종류 / 형식 기준만. 자세한 layout 은
/build/dogfood/README.md.
3. 단일 디렉토리 정책: source 문서 + KB state + logs 모두 /build/
dogfood/ 안 하나로. 매 도그푸딩 run 마다 kb/ 만 reset, 별 디렉토리
신설 X.
4. 금지 위치 명시: /tmp/kebab-*, /build/cache/dogfood*, /home/altair823/
KnowledgeBase, XDG paths 신규 사용 금지.
Source dirs 정리 (이번 commit 외 별 작업으로 완료):
- /build/cache/dogfood{,-p10b,-v017,-v018,-v0.19.0} 모두 삭제 (move 후).
- /home/altair823/KnowledgeBase, kebab-dogfooding 도 /build/dogfood/ 로 이동.
- XDG paths 는 /build/dogfood/_archive/xdg-state/ 로 snapshot.
최종 corpus: 6293 files (markdown/code/html/manifest/resources), 554M.
사용자 요청 — 사용자가 누적된 ad-hoc 도그푸딩 데이터를 /build/cache/
dogfood/ 한 곳에 collection 한 후, 도그푸딩의 필요 시점을 추론해
CLAUDE.md 에 정책 section 추가.
신규 section `## Dogfood trigger` (사이 Release 와 Naming):
- 도그푸딩이 필요한 시점 (6 trigger 분류: schema/migration, wire
schema/CLI, search/RAG, performance, language/locale, file/asset).
- Release-level: bump commit 이전에 evidence 명시 필수.
- 도그푸딩 데이터 보관소: /build/cache/dogfood/ 의 디렉토리 구조 +
README.md cross-link + /tmp/kebab-* 신규 사용 금지.
- 도그푸딩 결과 기록: HOTFIXES dated entry + release notes draft 의
4-단락 풀어쓰기 + DOGFOOD.md scenario catalog cascade.
실 작업:
- /build/cache/tmp/v0.20.1-* 5 디렉토리, /tmp/dogfood-* 2 디렉토리,
관련 log file 모두 /build/cache/dogfood/ 로 mv. config.toml 의
hard-coded path 자동 sed-replace.
- /build/cache/dogfood/README.md 신규 — 디렉토리 구조 + 신규 시나리오
시작 절차 + V007 시뮬레이션 패턴 + 정리 정책.
기대 효과: 도그푸딩 evidence 의 git-tracked HOTFIXES + draft release
notes 외에도 raw data 가 한 곳에서 자유롭게 재사용 가능. 새 release
의 도그푸딩이 이전 KB 위에서 incremental 확인 가능.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md §9 (도그푸딩 evidence cascade)
Plan: post-implementation infrastructure
사용자 실제 /home/altair823/KnowledgeBase/ (1781 markdown / 9050 chunk)
를 v0.20.1+N-gram supplement 포함 binary 로 backfill 재실행:
- Backfill duration: 26.6초 (9050 chunk, OnceLock 캐시 + 1000-row
batch transaction). ~3 ms/chunk amortized.
- '한국' query: V007 의 0 hit → V009 + N-gram 의 10 hit (Bug #8
functional closure 실측 검증).
- '한국어' query: 5 → 10 hit (morpheme + N-gram 동시 매칭).
- 영어 whole-token: 'token'/'pipeline'/'config' = 10 hit each
(V009 회귀 측면 정상).
Snippet evidence: KB 의 testdata/coding-md-corpus/*/...md 의
"문서를 한국어로 다시 정리하기" 패턴이 ko-dic 분해 + N-gram window
로 '한국' query 매칭 demonstrate.
기타 한국어 (서울, 지하철, 대한민국 등) 0 hit 는 KB corpus 의
단어 자체 부재 — data limitation, V009 implementation limitation X.
Test data 위치:
- /home/altair823/KnowledgeBase/ (사용자 실제 KB, 1781 markdown)
- /build/cache/tmp/v0.20.1-dogfood/kb/ (ingested SQLite + LanceDB)
- /build/cache/tmp/v0.20.1-dogfood2/corpus/ (한국어 wiki fixture)
- /build/cache/tmp/v0.20.1-v007strict/corpus/no-space.md (whitespace-less)
- /build/cache/tmp/v0.20.1-ngram/corpus/extra.md (대한민국, 한국정부, 주민등록번호)
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md §9 + Appendix B
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (dogfood evidence final)
#4 (사용자 요청): spec §6.2 의 Option β (sub-token 추가 emit) 를
v0.21.x P9 follow-up 에서 v0.20.1 implementation 으로 promote.
dogfood 의 ko-dic compound noun limitation (`대한민국`, `한국정부`,
`주민등록번호` 등 단일 token 정책) 해소.
Implementation (`crates/kebab-chunk/src/lib.rs::tokenize_korean_morphological`):
- 신규 helper `is_hangul()` — 한글 음절 (U+AC00..D7A3) + 자모
(U+1100..11FF, U+3130..318F) 판정.
- lindera output 의 각 morpheme 에 대해, 한글만 + 길이 ≥ 3 인 경우
sliding window 2-gram 추가 emit. `[한국정부, 한국, 국정, 정부]`
형태로 token list expand.
- 영어 / 숫자 / 혼합 token 은 supplement X (false positive 회피).
Tests (`crates/kebab-chunk/tests/tokenize_korean.rs`):
- `tokenize_korean_morphological_emits_2gram_for_long_morpheme`: 5 probe
fixture 중 supplement 발화 case 확인 (실측 `서울특별시` →
`[서울, 특별시, 특별, 별시]`, `대한민국` → `[대한민국, 대한,
한민, 민국]`).
- `tokenize_korean_morphological_no_2gram_for_english`: Rust optimization
fixture 에서 영어 substring (`Rus`, `ust`, `imi`) emit 없음 보장.
Dogfood evidence (`tasks/HOTFIXES.md` 2026-05-28 entry 보강):
- '대한', '한민', '민국' query 모두 hit (대한민국 의 sliding window).
- '특별', '주민', '등록' 같은 sub-token query hit.
- 영어 'tokenizer' query 는 corpus 부재로 0 hit (supplement X).
- Trade-off: DB size +20-30% (Korean-heavy), false positive 작은 risk.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md §6.2 (Option β promote)
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (post-implementation enhancement)
V009 한국어 morphological tokenizer 의 dogfood 검증 결과를 HOTFIXES
2026-05-28 entry 에 보강. 14 scenario 의 hit count + ko-dic 의
compound noun 분해 evidence (서울특별시 → [서울, 특별시]) + Option α
acceptance 의 known limitation 명시.
Reference corpus: DOGFOOD.md §2.1bis 의 korea-overview.md +
korea-compound.md (10 KB 합계, 2 markdown). KB ingest + 14 query
검증 모두 expected.
사용자 KnowledgeBase 같은 영어/code 중심 KB 에서 한국어 lexical
0-hit 가 정상임을 reference fixture evidence 와 분리해 사용자
오인 방지.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md §9
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (S11 + dogfood evidence)
opus PR-level final review (Approved with notes) 의 4 minor finding
mechanical 정정:
1. README.md — `kebab search` row 의 영어 substring 매칭 표현이
V007 시절 그대로였음. V009 의 whole-token 회귀 (substring → V002
동작) 를 정직히 명시 + vector/hybrid mode 권장 안내.
2. tasks/HOTFIXES.md — 2026-05-28 entry 의 file path 정정. lexical.rs
는 lindera 호출자가 아니라 build_match_string 의 MIN_QUERY_CHARS
3→2 갱신만; lindera helper 의 실제 owner 는 kebab-chunk/src/lib.rs.
ingest.rs 는 본 PR scope 외, eager backfill hook 위치는 kebab-app/
src/app.rs::App::open_with_config.
3. docs/wire-schema/v1/search_response.schema.json — `hint` field
description 이 V007 trigram 3-char minimum 시절 advisory 시그니처
그대로. v0.20.1 에서 helper retired + always-omit 사실 명시
(forward-compat 차원에서 field 만 schema 에 보존).
4. integrations/claude-code/kebab/SKILL.md — `hint` field 설명의
self-contradiction ("present only with trigram in edge cases" vs
"Korean 2-char now supported") 해소. retired + reuse 가능 명시.
PR-level reviewer recommendation: "Merge as-is — block 사유 아님 (모든
finding minor)". 본 commit 은 reviewer 의 옵션 1 (별 docs hotfix
commit) 채택.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (PR-level finding follow-up)
S3 의 Chunk struct 갱신 (kebab-core 의 tokenized_korean_text:
Option<String> field 추가) 가 모든 chunk snapshot JSON 의 serde
serialize 결과를 변경시킴. 10 snapshot fixture (9 AST chunker +
markdown long-section) 의 baseline 을 V009 형태로 regenerate.
각 snapshot 의 변경 = chunk JSON 마다 `"tokenized_korean_text":
null` field 추가 (대부분의 fixture 가 영어 코드라 lindera 의 None
fallback). 동작 변경 없음 — serde representation 의 cascade만.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md §6.2
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (S3 follow-up via S11 sanity)
V009 morphological tokenizer 작업 (S3 chunk + S4 backfill + S5
short_query_hint 제거 + S7 신규 tests) 의 형식 정리. 동작 변경 없음.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (S11)
CLAUDE.md §Release / binary version bump 의 두 트리거 모두 hit:
- 사용자 도그푸딩 필요 (Bug #8 한국어 2자 query 해소 — '한국', '서울',
'지하철' 검색 검증).
- frozen design contract 변경 (§5.5 chunks_fts 의 unicode61 + CASE
expression triggers + tokenized_korean_text column).
V009 + lindera ko-dic 형태소 분석기 통합 외에도 v0.20.x 의 logging
round 2 enhancement (PR #190) 가 같은 v0.20.x 시리즈에 포함되어
v0.20.1 patch release 시점에 함께 cut.
Build verification: ./target/release/kebab --version → kebab 0.20.1.
Spec: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md §12.1
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md (S10)
V009 한국어 morphological tokenizer 의 사용자 visible surface 변경 +
release notes scope 를 5 docs 에 cascade.
- README.md: kebab search 명령 row 에 한국어 2자 query 지원 명시.
- integrations/claude-code/kebab/SKILL.md: V007 3-char hint 제거 +
V009 2자 한국어 query 지원 1줄.
- HANDOFF.md: C task status 완료 flip + v0.20.1 release notes scope
에 본 변경 추가 + 머지 후 발견 summary 행.
- docs/ARCHITECTURE.md: embedding upgrade (e5-small → e5-large),
lindera-ko-dic FTS5 한국어 지원, version notes 추가.
- tasks/HOTFIXES.md: 2026-05-28 entry — Bug #8 V009 해소, lindera-ko-dic
실제 crate name (spec deviation), cargo-deny deferred, Path A
영어 substring 회귀 명시.
Spec: tasks/p9/p9-9-v0.20.x-korean-morphological-tokenizer-spec.md §7.4
Plan: docs/superpowers/plans/2026-05-28-v0.20.x-korean-morphological-tokenizer-plan.md
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
