kebab/docs/superpowers/handoffs/2026-05-28-v0.20.x-c-korean-morphological-tokenizer-handoff.md

title: v0.20.x next session handoff — C 한국어 morphological tokenizer created: 2026-05-28 source_session: 2026-05-27 ~ 2026-05-28 (v0.20.0 sub-item 1 + bugfix 1~4 + ingest log r1+r2) target_branch_candidate: feat/korean-morphological-tokenizer (가칭) priority: C (HANDOFF.md "v0.20.0 sub-item 1 머지 후 priorities" 순서: C → B → A → G)

다음 session handoff — C 한국어 morphological tokenizer (Bug #8 follow-up)

새 session 이 픽업해서 진행할 다음 작업의 self-contained context. C 진행 후 B → A → G 순서.

---

0. Repo state (handoff 시점)

• working directory: /home/altair823/kebab
• branch: main (HEAD 70507e9 — handoff doc 갱신 commit).
• 가장 최근 머지: PR #190 (7bbdc89a — logging round 2 4 enhancement merge).
• env: export CARGO_TARGET_DIR=/build/out/cargo-target/target
• fresh release binary: /build/out/cargo-target/target/release/kebab (main HEAD 빌드).
• workspace test 1370+ passed (logging r2 추가 후), clippy -D warnings clean.

지난 session 의 누적 surface 변경 (HANDOFF.md G section 의 release notes scope 참조):

• v0.20.0 sub-item 1 (PDF scanned OCR via qwen2.5vl:3b) — PR #189.
• Bug #2/#3/#4 (size cap / chunker_version / mojibake fixture).
• Bug #6/#7 (Identity-H marker / CLI --media help).
• Bug #9/#10/#11/#13/#14 (capabilities flag / config_not_found / OCR timeout / schema.models / empty query).
• Bug #11 follow-up — OCR timeout 60s → 180s (sweet spot 점진적 축소).
• Ingest log feature round 1 (file ndjson + LoggingCfg + per-run rotation).
• Ingest log feature round 2 (image_w/h capture + V008 SQLite mirror + CLI inspect ocr-stats/ocr-failures + retention) — PR #190.

falsified 또는 design-constraint 로 분류된 항목 (fix 안 함):

• Bug #8 → 본 C 항목의 대상.
• Bug #12 (Code block wire .code field, not .text).
• ask 한국어 phrasing-sensitive refusal (RAG corner case, NLI gate).

---

1. 본 작업 (C) 의 deliverable scope

1.1 Bug #8 의 현 상태

V007 trigram FTS5 tokenizer (migrations/V007__fts_trigram.sql, 2026-05-23 v0.17.0 release) 가 SQLite FTS5 의 default unicode61 을 trigram 으로 교체. 효과:

• 한국어 ≥3 char substring 검색 가능 ('서울특별시' hit, '검색' hit).
• 한계: ≥3 char query 만 보장. '한국' (2 char) 같은 query 는 trigram bucket 가 없어서 0 hit.
• 사용자 도그푸딩 (round 3 / round 4) 에서 '한국' / '서울' / '지하철' 0 hit 반복 — 사용자 search experience 의 가장 큰 surface.

1.2 Bug #8 design constraint vs follow-up

HOTFIXES 2026-05-22 및 V007 migration 본문 의 design rationale:

trigram indexes 3-character grams, enabling Korean partial matches. ... DB size grows (~2-10×), English lexical also moves to substring match (recall↑, precision↓), BM25 score distribution shifts.

즉 trigram 도입 자체가 substring matching 의 우선시 — 그러나 2 char query 한계는 결국 한국어 사용자 의 search experience 의 큰 노이즈.

1.3 본 sub-item 의 fix paths (spec drafter 가 결정)

Option A — morphological tokenizer 도입:

• jieba-rs (Rust) 또는 koma / komoran 같은 한국어 형태소 분석기.
• SQLite FTS5 의 external content + custom tokenize. (rusqlite 의 create_module 또는 c-style binding).
• 또는 FTS5 의 tokenize='unicode61' + 별 tokenized table 의 dual-index (token list 사전 분해 후 column 에 저장).
• 한국어 morpheme 분해 → 2 char query 도 morpheme boundary 와 일치 시 매칭 가능.

Option B — trigram 보존 + bi-gram supplement:

• 2 char query 의 경우 trigram 외 bi-gram fallback index. SQLite FTS5 의 tokenize='trigram' 외 별 tokenize='unicode61' 의 dual-table.
• query analyzer 가 2 char 일 때 bi-gram table 에 fallback.

Option C — query-side expansion:

• 2 char query 시 user 에게 hint ("3 char 이상 입력 권장") + 또는 vector search fallback.
• low scope, design 변경 0. 그러나 actual fix 가 아닌 workaround.

권장: spec drafter 가 jieba-rs (또는 비슷) 시제품 시도 후 결정. corpus_revision bump + V009 migration cascade 예상.

1.4 cascade risk

design §9 version cascade:

• FTS5 tokenizer 변경 = 새 V009 migration cascade.
• 기존 V007 trigram index 보존 (backward-compat 위해) vs DROP + 새 index 교체 — spec 결정.
• search wire schema 변경 0 (tokenizer 는 internal). 사용자 visible benefit = '한국' 같은 2 char query hit.

---

2. 새 session 의 첫 step (권장)

2.1 작업 시작 명령

새 session 시작 시:

@/home/altair823/kebab/docs/superpowers/handoffs/2026-05-28-v0.20.x-c-korean-morphological-tokenizer-handoff.md

위 file 을 읽고 진행. PR #189 / #190 의 cycle 동일 패턴 (spec → critic → drafter rewrite → closure → plan → plan closure → executor → dogfood → PR).

2.2 branch + omc-teams

새 branch 생성:

git checkout -b feat/korean-morphological-tokenizer

omc team spawn pattern (memory feedback_omc_teams_usage 따라):

• sequential single-team only (multi-team spawn fail).
• spawn 후 background polling shell (until omc team status <name> | grep -qE "phase=(completed|failed|done|stopped)"; do sleep 30; done) — run_in_background=true.
• spawn syntax: omc team 1:claude:writer --no-decompose "spec drafter ...".
• model routing: spawn 시 변경 X (memory: "OMC teams usage — model routing 미해결").

2.3 spec drafter brief 작성 시 핵심

• spec deliverable path: docs/superpowers/specs/2026-05-28-v0.20.x-korean-morphological-tokenizer-spec.md.
• code probe:
  • migrations/V007__fts_trigram.sql (current trigram migration).
  • tasks/HOTFIXES.md 2026-05-22 + 2026-05-24 PR-A entries (trigram history).
  • crates/kebab-store-sqlite/src/fts.rs (FTS5 rebuild helper).
  • crates/kebab-cli/src/main.rs::Search (search args + --match-string 등 query path).
• jieba-rs crate 의 license + maintenance + tokenization quality 검토 (별 sub-section).

---

3. workflow patterns (직전 4 round 의 패턴 따라)

1. spec drafter (omc-teams writer role) → 500-800 line spec.
2. closure critic round 1 (omc-teams critic role) — design feasibility + parent spec invariant + wire schema cascade + new substantive finding hunt. verdict = ACCEPT / NEEDS_REWRITE.
3. drafter rewrite (r1c) 만약 NEEDS_REWRITE.
4. closure critic round 2 — mechanical traceability matrix + 0 substantive new finding 만 ACCEPT.
5. plan drafter (omc-teams planner role) → 500-700 line plan, step decomposition + AC verifier.
6. plan closure pass (omc-teams verifier role) — step → spec traceability + verifier actionability + 가능 시 closure finding 직접 plan-level resolve.
7. executor (omc-teams executor role) — sequential N step + N commit + workspace test verify.
8. dogfood retest (직접 또는 별 background bash) — actual user-visible verify.
9. PR force-push 또는 새 PR 생성 (PR #189 = force-push pattern, PR #190 = 새 PR pattern — sub-item scope 결정).
10. 사용자 merge 결정.

---

4. 환경 + memory 참조

4.1 빌드 환경

export CARGO_TARGET_DIR=/build/out/cargo-target/target

# 빌드:
cargo build --release -j 4 -p kebab-cli

# workspace test:
cargo test --workspace --no-fail-fast -j 1

# clippy:
cargo clippy --workspace --all-targets -j 4 -- -D warnings

# per-crate test:
cargo test -p kebab-store-sqlite -j 4
cargo test -p kebab-cli -j 4

4.2 dogfood corpus

기존 KB:

• /build/cache/tmp/v0.20-r5-dogfood/ 또는 v0.20-r4-dogfood/ 의 corpus 재사용 가능 (실측 R5 + R6 후 cleanup 됨 — 다시 setup 필요).
• corpus 구성: markdown × 2 + code (Rust / Python / Dockerfile / k8s / shell) + PDF (mojibake / scanned / metro-korea).
• Ollama remote: http://192.168.0.47:11434 (qwen2.5vl:3b OCR, bge-m3 embed, gemma4:e4b LLM).

4.3 memory references

이 session 의 memory (이미 메모리 안):

• feedback_pr_workflow.md — 모든 task = gitea-pr + 리뷰 루프 모드.
• feedback_omc_teams_usage.md — omc team CLI 사용 절차 (sequential single-team only).
• feedback_worker_completion_polling.md — worker spawn 직후 background polling shell run_in_background=true.
• feedback_teammate_spawn_mode.md — agent 는 omc-teams 통해 별 tmux pane 으로 spawn.
• feedback_serial_build_only.md — cargo 동시 bg 금지 (직렬), -j 4 default.
• feedback_cargo_clean_policy.md — /build 4TB HDD 사용 시 routinely clean 금지.
• feedback_user_review_gates.md — brainstorming + writing-plans 의 사용자 컨펌 단계 skip. 핵심 trade-off 결정만 AskUserQuestion.
• feedback_readme_sync_rule.md — surface 변경 시 implementation PR 이 README + HANDOFF + ARCHITECTURE 동시 갱신.
• feedback_no_caveman.md — caveman 말투 금지, 자연스러운 한국어 산문.

4.4 release strategy

본 C 작업 후 — wire schema 변경 0 (search query path 의 internal tokenizer). 그러나 사용자 visible behavior 변경 (2 char query hit 가능). HOTFIXES entry 추가 + parent spec cross-link (CLAUDE.md "Spec contract" rule). C 완료 후 별 release 또는 G (v0.20.1) 의 patch release 시 함께 cut.

---

5. 가능한 next-next 작업 preview

C 완료 후:

• B — OCR dense page coverage (metro-korea page 8/13 timeout 해소). path: per-page max_pixels 동적 / column-level OCR / model upgrade. detail = HANDOFF.md.
• A — v0.20 의 deferred sub-items (sub-item 2 multi-region image / sub-item 3 PDF normalize / TODO #4 figure-table / TODO #5 Enricher trait).
• G — v0.20.1 patch release (round 1+2 surface 통합 release notes).

---

6. 본 handoff doc 의 path + commit

이 file: docs/superpowers/handoffs/2026-05-28-v0.20.x-c-korean-morphological-tokenizer-handoff.md.

새 session 에서 첫 명령:

@/home/altair823/kebab/docs/superpowers/handoffs/2026-05-28-v0.20.x-c-korean-morphological-tokenizer-handoff.md

또는 그냥 위 file 의 내용 paste.