---
title: v0.20.1 full dogfood findings — todo handoff
created: 2026-05-28
source_session: 2026-05-28 (v0.20.1 머지 + dogfood data consolidation + 전체 도그푸딩)
target_branch_candidate: fix/v0.20.2-dogfood-findings (가칭)
priority: 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**:
  ```bash
  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

```bash
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 후 도그푸딩 재실행 절차:

```bash
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: https://gitea.altair823.xyz/altair823-org/kebab/pulls/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 따라 진행.
