kebab/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md

title, created, source_session, target_branch_candidate, priority

title	created	source_session	target_branch_candidate	priority
v0.20.1 full dogfood findings — todo handoff	2026-05-28	2026-05-28 (v0.20.1 머지 + dogfood data consolidation + 전체 도그푸딩)	fix/v0.20.2-dogfood-findings (가칭)	dogfood 단계 발견 findings 의 fix / docs / behavior 검토

다음 session handoff — v0.20.1 전체 도그푸딩 finding 정리

새 session 이 픽업해서 이어 작업할 todo. 사용자 실제 corpus (/build/dogfood/corpus, 6293 file) 의 fresh ingest + §1~§11 도그푸딩 결과 finding 들 정리.

---

0. Repo + 환경 state (handoff 시점)

• working directory: /home/altair823/kebab
• branch: main (HEAD a0c7fa3 — dogfood 보관소 정책 commit)
• 가장 최근 머지: PR #191 (ebc6bf4 — V009 한국어 morphological tokenizer + N-gram supplement + eager backfill, v0.20.1).
• env: export CARGO_TARGET_DIR=/build/out/cargo-target/target
• fresh release binary: /build/out/cargo-target/target/release/kebab (v0.20.1, N-gram supplement 포함).
• workspace test pass + clippy clean + fmt clean (이전 session 확인됨).

도그푸딩 data 보관소 (CLAUDE.md ## Dogfood trigger 정책 따라):

• /build/dogfood/corpus/ — 6293 source file, format/category 별 분류
• /build/dogfood/kb/ — fresh full ingest 결과 (3940 docs, 34896 chunks, 3.4G)
• /build/dogfood/config.toml — canonical config (Ollama remote 192.168.0.47 endpoint 패치됨)
• /build/dogfood/logs/full-dogfood-20260528_144512.{ingest-json,ingest-stderr} — 도그푸딩 로그
• /build/dogfood/_archive/ — 이전 KB state + XDG snapshot (regeneratable, wipe 가능)

---

1. 발견된 todo (severity + priority)

각 todo 의 Brainstorming? 필드는 fix path 가 mechanical 인지 (구현 만 필요), 아니면 사용자 expectation / design trade-off 검토 가 필요한지 표시.

• 🧠 brainstorming 필수: 사용자 의도 / trade-off 가 명확하지 않아 단순 구현 전에 spec drafter + critic 또는 사용자 confirmation 필요. superpowers:brainstorming skill 우선 invoke.
• 🔧 mechanical: spec drift 또는 명확한 fix path. 별 brainstorming 없이 spec → plan → execution.
• 📝 mild discussion: 작은 trade-off 가 있으나 spec drafter 의 self-review 로 결정 가능.

🐛 P0 — bug 또는 사용자 expectation 과 다른 동작

Todo #1: Ask 영어 query 의 응답이 한국어 (Finding O)

• Severity: medium
• Brainstorming?: 🧠 필수 (response language policy = design 결정)
• Scenario: kebab ask 'What is RAG architecture?' --mode hybrid
• Observed: 답변이 "RAG는 ... 정의됩니다 [#1]" (한국어)
• Expected: 답변이 input query 의 언어 (영어) 와 매칭
• Suspected cause: prompt_template_version: rag-v2 가 응답 언어를 한국어로 강제. crates/kebab-rag/ 의 prompt template 또는 system message 검토 필요.
• Brainstorming 의 핵심 질문:
  • 한국어 corpus 위주 user 가 영어 query 던질 때 응답 언어는? (사용자 의도 = "영어로 답해줘" vs "내 KB 의 한국어 content 기반 한국어로 정리해줘")
  • 한국 + 영어 혼합 query → 어느 언어 우선?
  • LLM 의 자동 language matching (예: gemma4 의 default 다국어 응답) vs prompt 의 명시 강제?
  • 사용자 명시 옵션 (kebab ask --response-lang ko/en/auto) 도입 적절한지?
  • RAG citation 의 source 가 다른 언어 일 때 인용 표기 형식?
• Action (brainstorming 후):
  1. crates/kebab-rag/src/prompt.rs (또는 등가 location) 의 system prompt 확인.
  2. Brainstorming 결과 따라 default policy 결정 → spec drafter → plan → implementation.
  3. Test scenario: handoff 시점의 /build/dogfood/kb/ 에서 영어/한국어/혼합 query 응답 언어 확인.

Todo #2: bulk search input format 불명확 (Finding V)

• Severity: medium (docs + wire schema)
• Brainstorming?: 🔧 mechanical (실제 input shape 가 코드 안에 정의됨 — documentation + help 갱신만 필요)
• Scenario:

  echo '{"text":"한국","mode":"lexical","k":3}' | kebab search --bulk --json
  echo '{"query":{"text":"한국","mode":"lexical","k":3}}' | kebab search --bulk --json
  

• Observed: 둘 다 error.v1 invalid_input: "missing required field: query".
• Expected: bulk input 의 정확한 JSON shape 가 명확.
• Suspected location: crates/kebab-cli/src/bulk_search.rs (또는 등가) 의 ndjson parser. bulk_search_item.v1.schema.json 의 input schema 부재.
• Action:
  1. docs/wire-schema/v1/bulk_search_item.schema.json 의 input shape 명시 (가능하면 별 bulk_search_input.schema.json).
  2. kebab search --bulk --help 의 example 추가 (echo '...' | kebab search --bulk).
  3. docs/DOGFOOD.md 의 bulk scenario 예시 갱신.
  4. 가능하면 error 메시지에 expected shape hint 추가.

Todo #3: list docs 의 title 중복 (Finding Q)

• Severity: low (UX)
• Brainstorming?: 📝 mild discussion (3 가지 옵션 trade-off — spec drafter self-review 로 결정 가능)
  • Option A: human-readable 출력에 doc_path 보조 표시 (현재 --json 에만)
  • Option B: title 의 unique 화 ("Registry — Registry.java" 처럼 file basename suffix)
  • Option C: title 의 source 변경 — 첫 H1 → frontmatter title → 파일명 fallback 의 우선순위 명시
• Scenario: kebab list docs --json | jq '.[0:5]'
• Observed: 여러 다른 file 이 title: "Registry", title: "dispatch" 등 동일 title 로 반환 — heading-based title 추출이 unique 안 됨.
• Expected: 사용자가 list 만 보고 어느 file 인지 식별 가능.
• Action:
  1. crates/kebab-cli/src/commands/list.rs (또는 등가) 의 human-readable 출력에 doc_path 표시 (현재 JSON 에만 노출).
  2. 또는 title 의 unique 화 ("Registry — Registry.java" 처럼 file basename 추가).
  3. README 의 kebab list docs 동작 명세 갱신.

Todo #4: doc.lang = "und" 53% (Finding U)

• Severity: low (UX + accuracy)
• Brainstorming?: 🧠 필수 (doc.lang 의 의미 자체 재정의 필요 — semantic 결정)
• Scenario: kebab schema --json | jq '.stats.lang_breakdown' → {en: 1358, ko: 89, und: 2493}
• Observed: Java/Kotlin/C++ 등 code file 에서 자연 언어 감지 실패율 53%.
• Brainstorming 의 핵심 질문:
  • doc.lang 의 user-facing 의미 = "자연 언어" (natural language of comments / prose) vs "source language" (rust/python/etc.) vs "primary language" (혼합 시 dominant) 중 어느 것?
  • 사용자가 kebab search --lang ko 할 때 의도 = "한국어 prose 문서 찾기" vs "한국어 주석 포함 code 도 같이"?
  • Code 의 자연 언어 (예: Rust 코드의 한국어 주석) 처리 — comment 만 추출해서 lang detect 가 옳은지?
  • Tier 1 (AST) / Tier 2 (resource) / Tier 3 (paragraph) chunker 별로 doc.lang 의 의미 차이 허용 가능한지?
  • 별 doc.code_lang (source code language) + doc.nl_lang (natural language) 분리 도입?
• Action (brainstorming 후):
  1. crates/kebab-core/src/lang.rs (또는 등가) 의 lang detection 위치 확인.
  2. Code chunk 의 code_lang 이 이미 정확 — doc.lang 도 fallback 으로 활용할지 결정.
  3. 결정된 semantic 따라 spec drafter → plan → implementation.

⚠ P1 — Documentation drift

(모든 P1 todo 는 🔧 mechanical — wire schema 의 실제 동작이 source-of-truth, README/docs 만 sync)

Todo #5: fusion_score 위치 표기 (Finding H/L)

• Severity: low
• Brainstorming?: 🔧 mechanical
• Scenario: README 의 wire schema 예시
• Observed: README 의 fusion_score 가 top-level 같이 표기되어 있으나, 실제 wire schema 의 .retrieval.fusion_score.
• Action:
  1. README.md, docs/wire-schema/v1/search_hit.schema.json 확인.
  2. README 의 search response 예시 갱신 — .retrieval.{fusion_score, lexical_score, vector_score, lexical_rank, vector_rank} 구조 명확화.
  3. score (top-level) vs retrieval.fusion_score (nested) 의 의미 차이 명시.

Todo #6: score_kind="bm25" 의 의미 (Finding X)

• Severity: low
• Brainstorming?: 🔧 mechanical
• Scenario: kebab search --mode lexical 'tokenizer' → score_kind: "bm25", score: 0.943, fusion_score: 0.943, lexical_score: 0.943
• Observed: lexical mode 에서 fusion_score == lexical_score == score 동일.
• Expected: fusion_score 는 hybrid 전용임이 docs 에 명확.
• Action: README + wire schema docs 에 fusion_score 의 mode 별 의미 명시 (lexical/vector 에서는 single-mode score 와 동일, hybrid 에서는 RRF normalized).

Todo #7: schema --json 의 index_version vs lexical_index_version (Finding G)

• Severity: low
• Brainstorming?: 📝 mild discussion (rename 옵션 결정 — 별 brainstorming 없이 spec self-review 로 가능)
• Observed: kebab schema --json | jq '.models.index_version' → "v1" (wire schema 의 v1)
• Expected: lexical_index_version (fts5-v009-korean-morphological) 가 별도 필드. 두 의미 다름 — 사용자 혼동 가능.
• Action: schema.v1 JSON 의 index_version 이름 또는 documentation 변경. 가능 옵션:
  1. wire_schema_version: "v1" + lexical_index_version: "fts5-v009-..." 로 rename
  2. 현재 이름 보존 + README 에 명시
• 이미 lexical_index_version 은 search hit 의 index_version field 로 노출됨 — schema 의 top-level index_version 과 의미가 같지 않다는 점 documentation 화 필요.

💡 P2 — Setup gap (config default)

Todo #8: Ollama endpoint default 가 localhost (Finding M)

• Severity: low (setup)
• Brainstorming?: 📝 mild discussion (default 유지 vs env var override vs auto-ping 의 작은 trade-off)
• Scenario: kebab init 의 default config.toml
• Observed: endpoint = "http://127.0.0.1:11434" (localhost)
• Expected: 사용자 environment 가 remote ollama (192.168.0.47) 인 경우 init 후 수동 갱신 필요.
• Action:
  • localhost default 유지 (대부분 사용자 setup 와 일치)
  • kebab init 의 hint 메시지에 "remote Ollama 사용 시 endpoint 갱신 필요" 안내 추가.
  • 또는 KEBAB_OLLAMA_ENDPOINT 같은 env var 지원으로 override 편의 추가.

✅ P3 — 검증된 정상 동작 (fix 불필요)

다음은 이미 정상이며 finding 으로 분류되지 않음 (regression 방지 목적의 reference):

• §1 Ingest: 6275 scanned (.git/ 자동 제외), 3940 new, 2335 skipped (확장자 미지원 — html/output/sample 등 의도), 0 errors, 3시간 30분 완료.
• §2.1 Lexical: 한국어 2-char 모두 hit (한국 10, 서울 6, 지하철 5, 대한민국 4), N-gram supplement 정상 (동아시아 → [동아, 아시, 시아]).
• §2.2 Vector + §2.3 Hybrid: fusion_score 0.984, lexical_score + vector_score 분리.
• §3 Ask: 한국어 RAG + 거절 동작 + citation 정상.
• §4 Inspect chunk: text, tokenized_korean_text, heading_path, chunker_version 모두 정상 노출.
• §4 Fetch chunk: kind=chunk, target.text 가 .chunk.text 구조.
• §5 Version cascade: corpus_revision=2 (V004 seed 0 + V009 +1 + ingest +1).
• §6 Wire schema: search_response.v1, search_hit.v1, fetch_result.v1, error.v1.
• §11 Edge cases:
  • Empty query → error.v1 (invalid_input).
  • 1-char Korean → 0 hits (MIN_QUERY_CHARS=2 filter).
  • Long query (300 char) → 2 hits, no error.
  • Special chars token!@#$% → 10 hits (FTS5 가 punct 무시).
  • Korean + punct '한국, 형태소!' → 3 hits.
• p9-fb-32 stale doc indicator 정상 (indexed_at, stale=false).
• p9-fb-34 cursor pagination 정상 (next_cursor base64 {offset, corpus_revision}).
• p9-fb-36 filter (--code-lang rust, --media code) 정상.
• p9-fb-37 trace 정상 (lexical_ms / vector_ms / fusion_ms / total_ms).
• p9-fb-38 score_kind 정상.
• p9-fb-19 --no-cache 정상.

---

2. 권장 새 session 의 첫 step

2.1 작업 시작 명령

새 session 에서:

@/home/altair823/kebab/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md

2.2 우선 순위 + 작업 흐름

🧠 Brainstorming 필수 todo (2개) — superpowers:brainstorming skill 우선 invoke 후 spec 진입:

• Todo #1 (Ask 영어→한국어 응답): response language policy 가 design 결정. user intent / RRF 영향 / --response-lang flag 옵션 등 논의.
• Todo #4 (doc.lang=und 53%): doc.lang 의 user-facing semantic 재정의 (자연 언어 vs source language vs primary language). 별 field 분리 가능성도.

🔧 Mechanical todo (4개) — brainstorming 없이 spec drafter → plan → execution 진입 가능:

• Todo #2 (bulk search input format) — wire schema + help docs 갱신
• Todo #5/#6 (fusion_score / score_kind 의 docs 위치) — README + schema docs sync

📝 Mild discussion todo (3개) — spec drafter 의 self-review 로 trade-off 결정 가능:

• Todo #3 (list docs title 중복) — 3 옵션 (doc_path 보조 / title unique / source 변경)
• Todo #7 (schema index_version) — rename vs documentation 만
• Todo #8 (Ollama endpoint default) — localhost 유지 + hint 갱신 vs env var override

권장 순서 (P0 → P1 → P2):

1. Brainstorming 단계 먼저 (Todo #1, #4) — superpowers:brainstorming skill 로 design 의도 명확화. 사용자 confirmation 받은 후 spec → plan → execution.
2. Mechanical batch (Todo #2, #5, #6, #7) — 한 PR 으로 docs/wire-schema/v1 + README + bulk help 갱신.
3. Mild discussion batch (Todo #3, #8) — spec drafter self-review 후 small PR.
4. dogfood retest — 전체 v0.20.2 patch release 컷 직전.

2.3 branch + workflow

git checkout -b fix/v0.20.2-dogfood-findings

또는 finding 별 별 branch (예: fix/bulk-search-input-shape, fix/list-docs-title).

전체를 v0.20.2 patch release 로 묶을 경우 single branch. 각 finding 독립적이라 cherry-pick 도 가능.

omc team workflow:

• Small fixes (P1, P3): in-process Agent (sonnet) 로 직접 처리.
• Medium fixes (P0 Todo #1/#2): spec drafter (omc team writer) → plan → subagent-driven-development 권장.

---

2.4 추가 brainstorming 후보 (직접 finding 외)

도그푸딩 단계에서 부각된 미래 design 결정 후보. 위 todo 의 fix 와 별 — 별도 spec 으로 다룰 가능성:

🧠 BS-A: HTML corpus 지원

• Status: 도그푸딩 corpus 의 1415 HTML file 가 모두 skip (extension 미지원).
• Question: HTML 가 일반 user KB 의 흔한 source format (saved web pages, ref docs, etc.). 지원 안 함이 의도된 omission 인지 / Tier 3 paragraph fallback 으로 처리할 가치 있는지?
• Trade-off: HTML parser (markup stripping + heading extraction) 의 추가 dependency vs corpus coverage 확장. Tier 3 fallback 으로 충분?
• Spec scope: 한 sub-item 의 1 file 인 fixture 검증 시작 → real corpus 도그푸딩 확대.

🧠 BS-B: Tier 1/2/3 chunker 의 사용자 visibility

• Status: kebab schema --json 의 active_chunkers 에 14 chunker 노출. 사용자는 어느 file 가 어느 Tier 로 처리됐는지 모름.
• Question: kebab inspect doc <id> 의 응답에 tier_used: "Tier 1 (AST)" / "Tier 3 (paragraph fallback)" 같은 field 추가 가치 있는지?
• Trade-off: wire schema 확장 vs UX 명확성. Tier fallback debug 시 유용.

🧠 BS-C: 도그푸딩 자동화 (kebab dogfood subcommand?)

• Status: 도그푸딩이 수동 ad-hoc — /build/dogfood/corpus 으로 manual setup → CLI 명령들 sequential 실행.
• Question: kebab dogfood --scenario all 같은 sub-command 도입해서 DOGFOOD.md §1~§13 의 시나리오 자동 실행 + JSON evidence summary? release 마다 사용자 가 한 명령으로 검증 가능.
• Trade-off: CLI 표면 확장 vs 도그푸딩 reproducibility 자동화. 별 kebab-eval crate 와 overlap 가능 (eval = goldens 비교, dogfood = release 검증).

📝 BS-D: Code chunk 의 N-gram supplement 의미

• Status: 도그푸딩 통계 — Korean tokenized chunks 34847/34896 (99.86%). 즉 영문 code chunk 도 tokenized_korean_text 가 populated. ko-dic 의 영문 처리 결과 (영문 token + N-gram 미적용) 가 빈/유의미한지?
• Question: 영문 code chunk 의 tokenized_korean_text 가 항상 raw text 의 duplicate 면 storage 낭비. populate 안 하고 NULL 두는 게 더 효율?
• Trade-off: ko-dic 호출 비용 (이미 chunk 마다 발생) vs storage 절약.

📝 BS-E: Ingest 의 .git/ 자동 제외 명세 (Finding A 확장)

• Status: .git/ 디렉토리는 자동 builtin_blacklist 로 제외 (현재 의도된 동작), 그러나 .kebabignore 또는 docs 에 explicit 표기 없음. 사용자가 추가 builtin_blacklist 가 무엇인지 모름.
• Question: node_modules/, target/, .git/ 같은 builtin_blacklist 의 명세를 schema 의 capabilities.builtin_blacklist 또는 wire schema 에 노출?
• Trade-off: wire 확장 vs UX 명확성.

---

3. 도그푸딩 재실행 (regression 방지)

새 finding fix 후 도그푸딩 재실행 절차:

DG=/build/dogfood
KB=/build/out/cargo-target/target/release/kebab
CFG=$DG/config.toml

# Fresh KB (현재 KB 의 corpus_revision=2 상태에서 incremental ingest 도 OK)
# rm -rf $DG/kb && mkdir $DG/kb  # 전체 reset 시

# 또는 incremental
$KB --config $CFG ingest

# 발견된 finding 의 regression 시나리오만 다시 실행
$KB --config $CFG ask 'What is RAG architecture?' --hide-citations          # Todo #1
echo '{"text":"한국","mode":"lexical","k":3}' | $KB --config $CFG search --bulk --json  # Todo #2
$KB --config $CFG list docs --json | jq '.[0:5]'                            # Todo #3
$KB --config $CFG schema --json | jq '.stats.lang_breakdown'                # Todo #4
$KB --config $CFG search --mode lexical 'tokenizer' --k 1 --json | jq '.hits[0]'  # Todo #5/#6
$KB --config $CFG schema --json | jq '.models.index_version'                # Todo #7

---

4. References

• 이번 session 의 PR: #191 (머지됨, v0.20.1)
• 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
• HOTFIXES: tasks/HOTFIXES.md 2026-05-28 entry (V009 + N-gram supplement + dogfood evidence)
• Release notes draft: docs/release-notes/v0.20.1-draft.md
• CLAUDE.md ## Dogfood trigger policy section + dogfood 보관소 /build/dogfood/
• DOGFOOD scenario catalog: docs/DOGFOOD.md

5. 발견 finding 의 cumulative summary table

#	Finding	Severity	Category	Target todo	Brainstorming?
A	scan vs corpus 21 file 차이	none	.git/ 자동 제외 (의도)	—	BS-E (선택)
B	html 1415 skipped (extension)	none	의도 — html 미지원	—	BS-A (선택)
C	size_exceeded 5 files	none	의도 — config 의 max_size_kb 제한	—	—
D	lang_breakdown und=53%	low	UX	#4	🧠 필수
E	pdf=8 from ts-zod logos	none	부산물, 정상 동작	—	—
F	Korean tokenized 34847/34896	none	N-gram supplement 정상	—	BS-D (선택)
G	schema index_version="v1"	low	docs	#7	📝 mild
H	fusion_score location	low	docs	#5	🔧
I	Korean queries hit	none	V009 closure 확인	—	—
J	English whole-token regression	none	V009 회귀 정상	—	—
K	Vector search semantic	none	정상	—	—
L	fusion_score location docs	low	docs	#5	🔧
M	Ollama endpoint default localhost	low	setup	#8	📝 mild
N	(skipped, M 와 동일)	—	—	—	—
O	Ask 영어 query → 한국어 응답	medium	behavior	#1	🧠 필수
P	fetch chunk target.text path	none	jq query 실수, 실제 정상	—	—
Q	list docs title duplicate	low	UX	#3	📝 mild
R	Edge case error handling	none	정상	—	—
S	jq error in test script	none	내 query 실수	—	—
T	Korean + punct OK	none	정상	—	—
U	doc.lang = und	low	UX	#4	🧠 필수
V	bulk search input shape	medium	docs+schema	#2	🔧
W	code-lang filter	none	정상	—	—
X	score_kind="bm25" 의미	low	docs	#6	🔧

Brainstorming summary

• 🧠 필수 (2 todo): #1 Ask response language, #4 doc.lang semantic
• 🔧 mechanical (4 todo): #2 bulk input docs, #5 fusion_score docs, #6 score_kind docs, #7 schema field rename
• 📝 mild discussion (3 todo): #3 list docs title, #8 Ollama default
• 별 brainstorming 후보 (선택): BS-A HTML 지원, BS-B Tier visibility, BS-C 도그푸딩 자동화, BS-D code chunk N-gram, BS-E builtin_blacklist 명세

---

6. 본 handoff doc 의 path + commit

이 file: docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md.

새 session 시작 시:

@/home/altair823/kebab/docs/superpowers/handoffs/2026-05-28-v0.20.1-fulldogfood-findings-handoff.md

또는 본 doc 의 §1 finding list 직접 읽고 priority 따라 진행.