`ask_multi_hop` 의 probe_hits 가 gate 검사 후 throw away 되는 의도
명시 — pool 초기값으로 재사용 안 하는 *invariant clarity* rationale 을
코드 안에 doc. 향후 retrieve cost 가 multi-hop bottleneck 이 될 경우
재검토 hint 도 함께.
검증
- `cargo test -p kebab-rag -j 1 --test multi_hop` 10 모두 통과.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.18 cut 전 fb-41 multi-hop RAG 도그푸딩에서 발견된 **safety regression**
fix. 자세한 도그푸딩 결과는 `tasks/HOTFIXES.md` 의 2026-05-25 fb-41
pre-v0.18 entry + `/build/cache/dogfood-v018/results/SUMMARY.md` 참조.
## 문제 (S7)
Query: `What is the chemical formula of caffeine?` (KB 에 없는 fact).
- Single-pass `kebab ask`: retrieve top score 가 default `rag.score_gate
= 0.30` 미만 → `refuse_score_gate` → 안전한 refusal.
- Multi-hop `kebab ask --multi-hop`: **`grounded = true`**, 본문
`"카페인의 화학식은 C₉H₁₅N₃O 입니다 [#6]"` (hallucination — 실제
C₈H₁₀N₄O₂) + `[#6]` 가 Adam optimizer chunk 의 `g_t = ∂L/∂θ_i` 본문을
인용 (시각적 short structured token 매칭 trigger).
원인: `ask_multi_hop` 의 score-gate 검사가 *pool 의 top_score* 만 봤다.
multi-hop 의 pool 은 5 sub-queries 의 union — 한 sub-query 의 top score
가 gate 위면 다른 chunks 가 원본 query 와 무관해도 gate 통과 + synth →
LLM hallucinate.
## Fix
`ask_multi_hop` entry 에 **pre-decompose probe** 추가:
1. *원본 query* 로 retrieve 한 번 (LLM call 0회, ~ms).
2. probe empty → `refuse_no_chunks(None)` (decompose 안 함, hops=None).
3. probe top_score < gate → `refuse_score_gate(None)` (decompose 안 함).
4. probe pass → 기존 decompose / decide / synthesize flow 그대로.
Multi-hop 의 safety floor 가 single-pass 와 정확히 일치 — multi-hop 은
*원본 query 가 이미 KB 범위 내* 일 때만 cross-doc reasoning 추가.
비용: 한 번의 retrieve (수 ms), LLM call 없음. multi-hop 의 LLM-dominated
latency 대비 무시 가능.
## Tests
신규 3 회귀 핀 (`crates/kebab-rag/tests/multi_hop.rs`):
- `multi_hop_below_probe_gate_refuses_before_any_llm_call` — **S7 직접
회귀 핀**. low-score chunk + empty LM script → score_gate refusal, LM
calls 0회, hops=None. fix revert 시 즉시 panic.
- `multi_hop_empty_probe_pool_refuses_before_any_llm_call` — empty
retrieve 시 NoChunks refusal, LM calls 0회.
- `multi_hop_above_probe_gate_proceeds_to_decompose` — probe pass 시
full multi-hop flow 정상 (decompose + decide + synth).
기존 7 multi-hop test 의 `ScriptedRetriever` 에 *probe-pass entry*
prepend + `retriever_handle.calls()` expectation +1. test 2 / test 4
처럼 entry 두 개였던 곳도 prepend (3 entries).
`multi_hop_refuse_no_chunks_preserves_hops_trace` /
`multi_hop_refuse_score_gate_preserves_hops_trace` 의 의미 좁힘 — 이제
*decompose-driven* refusal (probe pass 후 sub-query retrieve 가 empty
또는 below-gate) 만 검증. *probe-driven* refusal 은 hops=None
(decompose 안 함) — 신규 test 가 그 path 핀.
## 검증
- `cargo test -p kebab-rag -j 1` — 10 multi-hop (7 갱신 + 3 신규) + 19
pipeline + 31 unit + 3 prompt_template + 3 streaming 모두 통과. 회귀
없음.
- `cargo clippy -p kebab-rag --all-targets -j 1 -- -D warnings` clean.
- 단일 crate 직렬 build (16 GB RAM 제약).
## 변경 없음
- Wire schema — `Answer.hops` shape 동일, `refusal_reason` enum 동일.
- 다른 도그푸딩 발견 (synthesize citation 일관성, latency, binary path
confusion) — v0.18.1 또는 별 PR 의 책임. HOTFIXES 의 "다른 도그푸딩
발견" 절에 명시.
## 다음
PR-7 머지 후:
1. Workspace `Cargo.toml` version 0.17.2 → 0.18.0 (minor bump).
2. HANDOFF.md / INDEX.md 갱신 + frozen design §3.8 multi-hop sub-section.
3. `gitea-release v0.18.0 --auto-notes`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
test `spawn_snapshot_multi_hop_into_askopts` →
`ask_state_multi_hop_field_default_false_and_round_trips` 로 rename.
이전 이름은 spawn 동작 검증을 약속했으나 본문은 단순 field
default + setter round-trip 만 검증 — name 과 실제 의도의 mismatch.
새 이름이 실제 검증 (field shape pin) 과 정확히 일치.
doc string 도 spawn 동작은 별 path (live dogfood) 로 검증된다고
명확히 표기 — test 의 책임 범위가 무엇인지 reader 가 즉시 파악.
검증
- `cargo test -p kebab-tui -j 1 --test ask` — 42 test (6 multi-hop
포함) 모두 통과.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
fb-41 multi-hop RAG 의 **마지막 component PR** (PR-5 머지 직후). TUI Ask
패널의 user-facing surface — F2 toggle, multi-hop badge, status panel
의 hop count summary, cheatsheet 안내. v0.18.0 cut 준비.
설계: docs/superpowers/specs/2026-05-25-p9-fb-41-multi-hop-rag-design.md
계획: docs/superpowers/plans/2026-05-25-p9-fb-41-multi-hop-rag.md (PR-6 단락)
## TUI surface
- `crates/kebab-tui/src/app.rs`:
- `AskState.multi_hop: bool` field + Default false. 사용자 토글
상태를 인-패널 보존, 대화 history 와 직교 — F2 flipping mid-
conversation 도 turns 보존 (다음 turn 만 다른 pipeline 으로 route).
- `crates/kebab-tui/src/ask.rs`:
- `handle_key_ask` 에 `(KeyCode::F(2), _) → s.multi_hop = !s.multi_hop`.
Mode-agnostic (physical function key — Normal/Insert 양쪽 작동, typing
ambiguity 없음). Briefing 의 candidate (F2 vs Ctrl-T) 중 F2 채택 —
Ctrl-M 은 Enter 와 collision 이미 명시, F2 가 cleanest.
- `spawn_ask_worker` 의 `AskOpts.multi_hop` 가 spawn 시점에 토글값
snapshot. 이후 F2 flip 은 다음 Enter 부터 적용 (in-flight turn 무영향).
- `render_input` 의 input pane title 에 `F2=multi-hop` binding 안내
추가 + prompt row 에 `multi-hop` badge (Success 녹색, toggled-on 일
때만). 사용자가 어떤 pipeline 으로 다음 query 를 보낼지 항상 가시.
- `render_status` 의 status panel 에 `multi-hop: N hops` line 추가
(last_answer.hops 가 Some 일 때만). forced_stop 발생 시
`forced_stop=K` suffix — depth/pool cap tuning 단서.
- `crates/kebab-tui/src/cheatsheet.rs`:
- Ask section 에 `F2 toggle multi-hop pipeline` entry 추가.
## 변경 없음 (의도된 deferral)
- `InspectTarget::Hop(turn_index)` variant — plan 의 PR-6 stretch goal.
per-iter hop trace detail 을 Inspect 패널에 노출하는 기능은 별 PR
(PR-6b 또는 v0.18 dogfood follow-up). PR-6 의 핵심 가치
(사용자가 multi-hop pipeline 을 토글하고 결과의 hop count 를 본다)
는 status panel 의 한 줄 summary 로 100% cover. Inspect 진입은
multi-hop 사용자가 *드물게* 필요한 surface — v0.18 cut 부담 회피.
- prompt_template_version (`rag-multi-hop-v1`) — 그대로.
- MCP / CLI surface — PR-4 / PR-5 의 책임.
## Tests (`tests/ask.rs` 신규 6 multi-hop pins)
- `f2_toggles_multi_hop_flag_from_insert_mode`: Insert 에서 F2 toggle
(fresh_app default mode).
- `f2_toggles_multi_hop_flag_from_normal_mode`: Normal 에서도 동일
— mode-agnostic 회귀 핀.
- `input_pane_shows_multi_hop_badge_when_toggled_on`: 토글 on 시
prompt row 에 `multi-hop` 등장 + title 의 `F2=multi-hop` binding
hint 등장.
- `input_pane_omits_multi_hop_badge_when_toggled_off`: 토글 off 시
prompt row 의 badge 부재 (title hint 는 유지 — 사용자 discoverability).
- `status_panel_summarizes_hops_when_answer_has_trace`: 3-hop trace
(Decompose + Decide + Synthesize) → `multi-hop: 3 hops` line.
- `status_panel_omits_hops_summary_for_single_pass`: hops=None → 본문
에 summary line 부재 (title binding hint 만).
- `spawn_snapshot_multi_hop_into_askopts`: AskState.multi_hop 의
field shape 회귀 핀 (default false / settable / round-trip).
## 검증
- `cargo test -p kebab-tui -j 1` — 신규 6 multi-hop + 기존 ask /
search / library / mode / cheatsheet / inspect / status_bar 모두
통과 (42 ask test + 10 mode + 기타). 회귀 없음.
- `cargo clippy -p kebab-tui --all-targets -j 1 -- -D warnings` clean.
- 단일 crate 직렬 build (16 GB RAM 제약).
## v0.18.0 cut (다음 단계)
- Workspace `Cargo.toml` version 0.17.2 → 0.18.0 (minor — surface
확장 + new prompt_template_version `rag-multi-hop-v1`).
- HANDOFF.md / HOTFIXES.md / INDEX.md 갱신 (fb-41 entry 정리).
- `gitea-release v0.18.0 --auto-notes`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`ask_tool_routes_multi_hop_true_to_decompose_first` 의 error code
검증을 더 견고하게 — `model_unreachable | timeout` 둘 다 accept.
환경 차이 (즉시 ECONNREFUSED vs connect timeout) 가 다른 wire code
로 분류돼도 dispatch divergence 자체 (schema_version=error.v1 +
isError=true vs single-pass 의 answer.v1 grounded=false) 는 동일하게
검증.
검증
- `cargo test -p kebab-mcp -j 1 --test tools_call_ask_multi_hop` 2 통과.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`answer.schema.json` 의 `refusal_reason` description 의 PR 번호 정정:
`multi_hop_decompose_failed` 도입 시점 = PR-2 (#167, RefusalReason variant
+ ask_multi_hop decompose-failure 분기). PR-3a (#168) 는 `Answer.hops`
field + RagCfg knob 만 — refusal variant 와 무관.
검증
- `cargo test -p kebab-cli -j 1 --test wire_ask_multi_hop` 4 모두 통과.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
test 7 의 `i32_below_gate_chunk` helper rename → `seed_low_score_chunk` +
반환 shape 을 `(chunk_id, doc_id)` tuple 로 확장. `i32` prefix 가 Rust
integer 타입과 충돌하던 가독성 문제 해소 + 호출자가 `id32("d_low")` 를
재계산하지 않도록 id 페어를 single source of truth 로 통합.
검증
- `cargo test -p kebab-rag -j 1 --test multi_hop` — 7 모두 통과.
- `cargo clippy -p kebab-rag --all-targets -j 1 -- -D warnings` clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
(A) ScriptedLm doc 의 `Arc<Vec<String>>` 표기 → 실제 구현 (`Vec<String>` +
`AtomicUsize`, 외부에서 `Arc::new(ScriptedLm::new(...))` 로 wrap)
반영.
(B) ScriptedLm::new doc 의 미존재 `with_*` builder 언급 제거.
(C) refuse path 의 hops 보존 회귀 핀 2 건 추가 (`tests/multi_hop.rs`):
- `multi_hop_refuse_no_chunks_preserves_hops_trace`: empty pool →
`refuse_no_chunks(Some(hops))` → Answer.hops = Some([Decompose,
Decide]).
- `multi_hop_refuse_score_gate_preserves_hops_trace`: top score 0.10
< 0.30 gate → `refuse_score_gate(Some(hops))` → 같은 shape.
refuse_* widening + ask_multi_hop 의 forwarding wiring 이 reverting
되면 두 test 가 회귀 잡음.
(D) test 5 의 redundant `assert_ne!(.., Some(MultiHopDecomposeFailed))`
제거 — `assert_eq!(.., None)` 이미 함의. 메시지에 의도 통합.
검증
- `cargo test -p kebab-rag -j 1 --test multi_hop` — 7 (5+2) 모두 통과.
- `cargo clippy -p kebab-rag --all-targets -j 1 -- -D warnings` clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR-3b 의 분할 첫 PR. ask_multi_hop 의 fixed depth=2 → dynamic N-hop.
ScriptedLm helper + 5+ integration tests (happy-path 통합 검증) 는
PR-3b-ii 분리. 본 PR 의 회귀 핀 = 기존 PR-2 의 2 integration test
통과 (decompose garbage refusal + multi_hop=false single-pass keep).
- `RagPipeline::multi_hop_decompose` 시그니처 변경 — `Result<
(Option<Vec<String>>, u32)>` (parsed result + LLM call latency_ms).
caller (`ask_multi_hop`) 가 hop trace 의 `llm_call_ms` stamp.
- `RagPipeline::multi_hop_decide` helper 신규. decide LLM call →
`parse_decompose_response` 으로 `Option<Vec<String>>` 반환. None
또는 empty array 가 stop signal (refusal 아닌 graceful degrade).
- `MULTI_HOP_DECIDE_SYSTEM_PROMPT` const 신규.
- `MULTI_HOP_DECOMPOSE_USER_TEMPLATE` const 제거 + `format!` named
arg 사용 (PR-2 회차 1 carry-over fix). compile-time substitution
check — 사용자 query 안에 `{max_sub_queries}` literal 있어도
mis-replace 회피.
- `ask_multi_hop` 의 §1 (Decompose) + §2 (Retrieve) 영역을 dynamic
loop 으로 재작성:
- iter 0 = decompose, HopRecord 추가 (kind=Decompose).
- iter 1..=max_depth = retrieve current_sub_queries → pool dedup
→ decide LLM call (forced_stop / pool_cap_hit 시 skip).
HopRecord 추가 (kind=Decide, sub_queries=new_sub_queries,
context_chunks_added, forced_stop, llm_call_ms).
- `max_pool_chunks` 도달 시 `pool_cap_hit = true` → 그 iter 의
HopRecord 가 `forced_stop = true` + decide LLM call skip.
- depth 도달 (`iter >= max_depth`) 시 동일하게 forced_stop.
- decide parse failure 또는 empty array → loop break (early
synthesize, NOT refusal — spec §9 graceful degrade).
- §6 (Generate) 시작 시 `synthesize_started: Instant::now()` 별
stamp → §8 Build Answer 직전 `HopRecord { kind=Synthesize,
llm_call_ms = synth_ms }` 추가. happy path 의 Answer literal
`hops: Some(hops)` 채움 (`hops: None` → `Some(...)` 변경).
- doc comment 갱신: "PR-2 scope (fixed depth=2)" → "PR-3b-i
scope (dynamic N-hop)". refusal path 의 hops trace 손실 caveat
명시 (PR-3b-ii / follow-up 에서 helper signature 확장 시 해결).
기존 회귀 핀 (PR-2 의 2 integration test):
- `ask_multi_hop_dispatches_and_decompose_garbage_refuses`:
decompose garbage → RefusalReason::MultiHopDecomposeFailed +
정확히 1 LLM call. PR-3b-i 의 시그니처 변경 후도 통과.
- `ask_with_multi_hop_false_keeps_single_pass_path`: 영향 없음.
56 unit + integration test 모두 통과 (kebab-rag).
Wire 영향: `Answer.hops` 가 multi-hop happy path 에서 emit. JSON
Schema additionalProperties default `true` 라 wire breaking 아님
(PR-3a 의 review 확인). schema.json 명시 갱신은 별 PR
(PR-3b-ii 또는 PR-4 의 schema sweep).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- `parse_decompose_response_drops_partial_empty_keeps_valid` 신규
회귀 핀 — `["", "valid q", " "]` → `["valid q"]` (trim+filter
chain 동작 pin).
- `multi_hop_decompose` 의 `stop: Vec::new()` 옆 doc comment 추가 —
의도 명시 (instruction-following 모델 기대 + prose 추가 시
MultiHopDecomposeFailed refusal 가 policy). 회차 1 question 의
답변.
- plan 의 PR-3 implementation order 에 회차 1 carry-over 추가:
1) ask + ask_multi_hop 의 §4-§9 mirror → 공통 helper 추출,
2) decompose template 의 substitution corner case → format!
named arg 으로 교체.
회차 1 의 다른 suggestion (mirror refactor, substitution corner
case, history block helper) 는 PR-3 합리적 timing 으로 plan 에
명시 — 회차 2 reply 에 정리.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR-2 of fb-41 multi-hop RAG. Decompose + retrieve + synthesize 3-stage
pipeline가 `opts.multi_hop=true` 일 때 dispatch. Dynamic decide loop
는 PR-3.
- `AskOpts.multi_hop: bool` 필드 추가 + `impl Default for AskOpts`
도입 (HOTFIXES 2026-05-07 의 known limitation 해소). 9 explicit
init site 모두 `multi_hop: false` 추가 — Default 도입으로 향후
`..Default::default()` 점진 migrate 가능.
- `RagPipeline::ask` 의 entry 에 dispatcher 한 줄
(`if opts.multi_hop { return self.ask_multi_hop(...) }`).
- `RagPipeline::ask_multi_hop` 신규 method. 1) decompose LLM call
→ JSON array of strings parse, 2) 각 sub-query 로 retrieve +
chunk_id dedup pool, 3) score gate / no-chunks 가드, 4)
pack_context (single-pass 와 helper 공유), 5) synthesize LLM
call w/ MULTI_HOP_SYNTHESIZE_SYSTEM_PROMPT, 6) citation extract
+ Answer build. `prompt_template_version` = "rag-multi-hop-v1"
로 stamp — eval `compare` 가 single-pass vs multi-hop 분리.
- Prompt const 신규: MULTI_HOP_DECOMPOSE_SYSTEM_PROMPT +
MULTI_HOP_DECOMPOSE_USER_TEMPLATE + MULTI_HOP_SYNTHESIZE_SYSTEM_PROMPT
+ PROMPT_TEMPLATE_VERSION_MULTI_HOP + MULTI_HOP_MAX_SUB_QUERIES_DEFAULT.
- `kebab_core::RefusalReason::MultiHopDecomposeFailed` variant 신규.
Cascade: kebab-store-sqlite `refusal_reason_label` + kebab-tui `ask
refusal render` exhaustive match 갱신.
- `parse_decompose_response` + `strip_markdown_json_fence` helper —
markdown code fence (```json / ```) strip + JSON array of strings
parse + trim + drop empty + cap at MULTI_HOP_MAX_SUB_QUERIES_DEFAULT.
None 반환 시 caller 가 `MultiHopDecomposeFailed` refusal.
Tests (55 passing total, 8 신규):
- 6 unit (parse_decompose_response 의 bare array / fence variants /
garbage / cap / trim 회귀 핀).
- 2 integration: `ask_multi_hop_dispatches_and_decompose_garbage_refuses`
(decompose garbage → MultiHopDecomposeFailed + 정확히 1 LLM call) +
`ask_with_multi_hop_false_keeps_single_pass_path` (회귀 핀, 기존
caller 자동 backwards-compat).
Happy-path multi-hop (decompose 성공 → synthesize) 의 integration
test 는 ScriptedLm helper 가 PR-3 의 decide loop 와 함께 도입될
때 같이 추가. 현 `MockLanguageModel` 는 canned single response 라
2-LLM-call sequence 핀 불가.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- `mh-s-004` 의 `must_contain: ["i"]` 한 글자 → `["INSERT", "i 입력모드"]`
보강. trigram 0-hit + noise 매칭 위험 해소.
- 3 question 영어 변경 (`mh-c-005` / `mh-i-001` / `mh-s-002`) — fixture
의 lang 다양성 mix (12 ko + 3 en). 영어 dogfood 시 measurement gap
회피.
- plan 의 PR-1 단락이 outdated (kebab-eval crate 미survey 단계 작성 →
실제 PR 와 deviation). actual 변경 명시 + 초안 대비 deviation 명시.
회차 1 의 다른 2 suggestion (mh-c-002 의 `v0.17.2` hard-coded, 15
question / 5-per-bucket 회귀 핀의 frozen size) 은 baseline anchor 의도
적 freeze — 회차 2 reply 에 명시.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR-1 of fb-41 multi-hop RAG (spec: docs/superpowers/specs/2026-05-25-
p9-fb-41-multi-hop-rag-design.md, plan: docs/superpowers/plans/2026-
05-25-p9-fb-41-multi-hop-rag.md).
XL 작업의 첫 PR — baseline 측정 anchor 만 추가. RAG pipeline 미변경,
fixture file + parse 회귀 핀.
사용자 결정 4 axis (2026-05-25):
- approach: query decomposition (LLM 서브-질문)
- trigger: explicit `--multi-hop` flag
- MVP scope: dynamic N-hop (LLM 이 depth 결정, decompose seed +
ReAct-style decide loop hybrid)
- eval: multi-hop golden set 먼저 (본 PR)
본 PR:
- `fixtures/multi_hop_golden.yaml` 신규. 15 question (5 cross-doc +
5 intra-doc + 5 single-fact negative). 기존 `GoldenQuery` struct
그대로 사용 — 별 loader / type 변경 없음. `expected_chunk_ids`
비어 있어 curator 가 `kebab ingest` 후 채울 수 있는 template
형태. `must_contain` 으로 baseline 측정 가능 (P5-2 metric).
- `crates/kebab-eval/tests/loader.rs::loads_multi_hop_golden_fixture`
신규 회귀 핀. fixture parse OK + 15 question + 5/5/5 bucket
분포 + 모든 question 에 must_contain 최소 1 개.
baseline 측정 protocol (별 run, commit 에 artifact 안 포함):
1. v0.17.2 binary 로 single-pass `kebab eval run --fixture
multi_hop_golden.yaml` 실행
2. P@5, P@10, must_contain pass rate, citation_coverage 캡처
3. PR-3 (dynamic iter 머지) 후 동일 fixture + `multi_hop=true` 로
재실행 → Δ 비교
PR 분할 6 단계 (plan 참조): PR-1 (본 PR — fixture only), PR-2
(RagPipeline::ask_multi_hop fixed depth=2), PR-3 (dynamic iter),
PR-4 (CLI flag + wire), PR-5 (MCP + SKILL.md), PR-6 (TUI toggle +
trace render). 마지막 PR 후 v0.18.0 cut.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.17.1 post-dogfood polish cut. 두 PR 묶어 release:
- PR #164 — `[image.ocr] request_timeout_secs` 별 노브 (v0.17.1
미진행 closure). LLM 패턴을 OCR 어댑터에 동일 적용, 별 노브로
분리 (OCR vs LLM 의 cold start 패턴 차이로 독립 조절).
- PR #165 — `heading_path` FTS5 column filter 로 text-only 매칭
+ raw-mode escape hatch (2026-05-24 v0.17.0 trigram entry 의
JSON 노이즈 closure). lexical.rs 가 non-raw 분기 결과를
`text : (<expr>)` 로 wrap, 색인 자체는 V007 verbatim 그대로
유지. raw mode `'heading_path : <token>'` 로 opt-in 가능.
둘 다 additive (옛 config 호환) + re-ingest 불필요. binary 교체만.
HANDOFF 한 줄 요약 + 머지 후 결정 절에 v0.17.2 entry 추가.
HOTFIXES 의 두 entry anchor 가 `post-v0.17.1 dogfood` → `v0.17.2`
로 갱신.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
HOTFIXES entry 의 **MCP / agent 가시성** 단락이 회차 1 의 SKILL.md
추가 결정과 contradiction (`별도 SKILL.md 갱신 불필요` 잘못된
표기). 갱신 사실 + 새 escape hatch 가 v0.17.0 raw mode pattern
위에 build 됐다는 점 명시.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- HOTFIXES test 카운트 표기 정정: `9 신규 / 갱신 unit test` 의 산수
ambiguity → `9 unit test (8 갱신 + 1 신규) + 2 신규 통합 test = 11
total` 로 명시.
- SKILL.md (Claude Code integration) 의 search 절에 column scoping +
heading_path raw-mode escape hatch 안내 한 bullet 추가. 회차 1
의 follow-up suggestion 반영 — heading 검색 의도 agent 가 새
escape hatch `'heading_path : <token>'` 를 발견 가능.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.17.0 trigram tokenizer entry 가 미수정으로 남겨둔
heading_path_json JSON 노이즈 (HOTFIXES 2026-05-24) closure.
trigram 이 chunks_fts.heading_path 컬럼 (V002/V007 트리거가
chunks.heading_path_json 그대로 INSERT) 의 JSON 표기 + 안의 path
세그먼트 (app, src) 까지 3-gram 색인해서 query 가 우연히 false
positive hit 하는 문제. column filter 채택 — heading 색인 유지
(V007 verbatim 불변), 매칭 대상만 text 컬럼 한정.
- build_match_string 가 non-raw 분기에서 combined expression 을
`text : (<expr>)` 로 wrap. FTS5 column filter syntax 가 OR/AND
sub-expression 허용.
- Raw mode (`'...'`) 는 그대로 — 사용자가 명시 의도로
`'heading_path : agent'` 같은 explicit opt-in 가능 (escape hatch).
- 8 기존 build_match_string unit test expected string 갱신 +
`build_match_string_raw_mode_preserves_heading_filter` 신규.
- `lexical_heading_only_token_does_not_hit_default_mode` 신규 회귀 핀
(heading-only unique token 이 default mode 에서 0 hit).
- `lexical_raw_mode_can_opt_into_heading_path_filter` 신규 — 같은
fixture 가 raw mode 로 hit 확인 (escape hatch 동작 핀).
사용자 영향: lexical / hybrid 검색의 본문 precision ↑. recall
변화 없음 (text 본문 token 매칭은 동일). re-ingest 불필요 (FTS
query 시점 매칭만 변경). lexical_snapshot_run_1 + hybrid_snapshot
도 fixture regenerate 불필요 (text 본문 매칭 query 라 BM25 동일).
HOTFIXES: 2026-05-24 v0.17.0 entry 의 `heading_path_json` 노이즈
항목 closure 표기 + 새 2026-05-25 post-v0.17.1 dogfood entry 추가.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- HOTFIXES 헤더 `v0.17.2` (vaporware) → `post-v0.17.1 dogfood`
로 변경, release tag 결정과 무관하게 정확한 anchor.
- HOTFIXES caller 수 `6 (5+3)` → `9 call site (6+3)` 으로 정정.
- OcrCfg.request_timeout_secs doc 의 edge case 가 LlmCfg sister
doc 과 동일한 구체 예제 (`u64::MAX`, `86400`) + reqwest 0.12.x
명시 주석으로 강화.
- LLM + OCR 양쪽의 legacy TOML fixture (78 줄 거의 동일) 를
module-level `LEGACY_PRE_TIMEOUT_TOML` const 로 추출. 두 test
가 동일 source 공유 → 옛 schema 가 또 변하면 한 곳만 수정.
reqwest::Duration::ZERO fact-check (회차 1 점 5) 는 회차 2
reply 에서 검증 결과 보고.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.17.1 (PR #162) 가 LLM 쪽 hard-coded 300s 를 [models.llm]
request_timeout_secs 로 풀어준 것과 같은 패턴을 OCR 어댑터에 적용.
사용자 결정으로 별 노브 분리 ([image.ocr] request_timeout_secs) —
OCR 는 LLM 대비 cold start 패턴이 달라 독립 조절이 편함.
- OcrCfg.request_timeout_secs: u64 (serde default 300)
- KEBAB_IMAGE_OCR_REQUEST_TIMEOUT_SECS env override
- OllamaVisionOcr::build / from_parts 시그니처에 timeout 인자 추가
- REQUEST_TIMEOUT 상수 제거
- 3 신규 unit test (default / env / legacy parse) — LlmCfg 패턴 그대로
- HOTFIXES 2026-05-25 v0.17.1 entry 의 두 미진행 항목 모두 closure
(OCR timeout = 본 PR, --stream docs = PR #163 에서 이미 완료)
기존 config / 옛 KB 영향 없음 — 새 필드는 default 로 채워지고
동작도 동일 (300s). vision 모델 cold start 가 길면 env 또는
config 로 늘릴 수 있음.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- HANDOFF 한 줄 요약 v0.17.0 → v0.17.1 + release URL 추가
(v0.17.1 cut: PR #162 + #163 한 묶음 안내).
- 머지 후 발견 deviation 절: 2026-05-25 v0.17.1 entry 추가.
- INDEX P10 Dogfooding Feedback section 하단에 'v0.17.1
post-dogfood polish' subsection 추가 (PR #162, #163 각 한 줄).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.17.1 patch release — v0.17.0 post-dogfood follow-up 두 PR 머지 후.
- PR #162: [models.llm] request_timeout_secs config + 권장 모델 가이드
- PR #163: sudo 없이 ollama 설치 가이드 + kebab ask --stream UX 권장
둘 다 additive only (config field) + docs only — wire breaking 없음,
기존 사용자 영향 없음. patch bump.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
확장 도그푸딩에서 사용된 두 패턴을 README + SMOKE 에 옮김.
(1) sudo / systemd 없이 격리 디렉토리에 ollama 설치 — tarball 받아
/opt/ollama/{bin,models,logs} 같은 사용자 디렉토리에 풀고
OLLAMA_MODELS env 로 모델 위치 분리. 컨테이너 / WSL2 / 회사
머신 등 root 권한 제약 환경에 유용. 도그푸딩 머신에서
/build/cache/ollama 로 같은 패턴 검증.
(2) cold start 가 긴 모델 (8B+ 또는 첫 호출) 은 `kebab ask --stream`
권장 — 동일 inference 시간이라도 progressive 토큰이 5분 timeout
한도 안에서 빠르게 surface 됨. p9-fb-33 의 streaming 경로를
UX 개선 권고로 명시.
코드 변경 없음 — docs only. README + SMOKE 두 군데 동일 패턴
sub-bullet + bash snippet.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR #162 워커 리뷰 반영.
- MEDIUM (W2) + LOW (W1): request_timeout_secs = 0 이 reqwest 의
의미상 disable 이 아닌 instant timeout (모든 요청 즉시 실패).
LlmCfg field rustdoc + ollama.rs module-level comment + README
세 군데에 명시 + u64::MAX / 86400 같은 large finite 값 권장.
- NIT (W1): HOTFIXES 2026-05-25 entry 의 '답변이 인 5분' typo →
'답변이 5분' (1자 삭제).
- NIT (W1): README + HOTFIXES 의 '확장 도그푸딩' 내부 jargon →
'후속 도그푸딩' 으로 통일.
코드 동작 변경 없음 — doc only. cargo test request_timeout 3 PASS.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.17.0 확장 도그푸딩 (2026-05-25) 에서 발견된 두 가지를
한 PR 에 묶음.
(1) llm.generate_stream 의 hard-coded 300s timeout 을 config 노브로
빼냄. 8B+ 모델 (gemma4:e4b 등) 은 CPU only 환경에서 5분
안에 첫 RAG 답변 못 마치고 `error: kb-rag: llm.generate_stream`
으로 떨어지던 문제.
- kebab-config::LlmCfg 에 request_timeout_secs: u64 additive
필드 (#[serde(default = "default_llm_request_timeout_secs")]
default 300). 옛 config 가 키 누락해도 그대로 파싱 + 동일
동작.
- env override KEBAB_MODELS_LLM_REQUEST_TIMEOUT_SECS.
- kebab-llm-local::ollama.rs 의 REQUEST_TIMEOUT 상수 제거 →
OllamaLanguageModel::new 가 Duration::from_secs(
llm.request_timeout_secs) 로 reqwest client 빌드. doc
comment 도 동일 갱신.
- 신규 unit test 3 — default 300 핀 / env override / legacy
config (필드 누락) backward-compat.
(2) docs — README 사전 요구 절 + docs/SMOKE.md ollama 안내에 한 단락:
CPU only / RAM ≤ 16 GB 환경 ⇒ ≤ 4B Q4 모델 권장
(gemma3:4b / qwen2.5:3b / phi3:mini). 8B+ 시도 시 timeout
패턴 사전 안내. request_timeout_secs 노브 사용법.
HOTFIXES 2026-05-25 entry — 위 두 변경 + 미진행 사항
(kebab-parse-image OCR 의 같은 hard-coded 300s 는 scope 외
follow-up 으로 등재 + ask --stream 권장 강조 후속) 기록.
workspace cargo test -j 1 + clippy 통과. 코드 변경은 backwards-compat
(additive serde field) 라 기존 사용자 영향 없음.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 한 줄 요약 v0.16.1 → v0.17.0 + release notes URL + PR-A/B/C
한 줄 요약.
- 머지 후 발견 deviation 절: PR-A 외 PR-B / PR-C 의 2026-05-24
closure entry 추가.
- '다음 task 후보' 의 P10 round 2 follow-up 라인: 세 항목 모두
v0.17.0 closure 표시.
- 'P10 dogfooding 백로그' 의 chunk_breakdown + C typedef 두
항목도 ✅ v0.17.0 closure.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.17.0 release cut — PR-A (한국어 trigram FTS tokenizer + lexical
builder + hint surface) + PR-B (C typedef alias unit + parser_version
cascade + orphan purge) + PR-C (code_lang_chunk_breakdown additive
wire field) 셋 머지 후.
Breaking changes:
- V007 migration (chunks_fts unicode61 → trigram) — chunks 원본 /
embedding / vector 불변, FTS shadow 자동 backfill. 사용자는 다음
open 시 V007 즉시 적용 (re-ingest 불필요). kebab.sqlite 파일 크기
~2-5배 또는 수백 MB 증가.
- 영어 lexical 검색이 substring 매칭으로 동작 변경 (token →
tokenization/tokenizer 도 hit, recall ↑ / 단어 경계 ↓).
- C parser_version code-c-v1 → code-c-v2 (typedef alias 추출
cascade). 같은 file 의 옛 doc/chunks/vector 는 same-workspace_path
orphan purge 가 자동 정리.
Additive (backwards-compat):
- SearchResponse.hint additive field — 한국어 2자 query 등 trigram
비호환 시 안내.
- schema.v1.stats.code_lang_chunk_breakdown additive field — chunk
단위 언어별 분포.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
실제로 doc count 임을 명시 (PR #161 워커 리뷰 MEDIUM 반영)
JSON schema description 은 PR-C 본체에서 'code chunk count' →
'doc count' 로 정정했으나 Rust struct field 의 rustdoc 은 같은
오기재를 그대로 carry — Gemini round 2 가 JSON schema 만 봤고
rustdoc 은 miss. 워커 둘 다 동일 finding (MEDIUM).
implementation 변경 없음 — 의미가 doc count 였던 사실이 처음부터
일관. wording 만 맞춤.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- tasks/HOTFIXES.md: 새 2026-05-24 PR-B closure entry — extractor 의
type_definition 분기, PARSER_VERSION bump, same-workspace_path
orphan purge, 사용자 영향, 잔여 nested typedef Risks.
- tasks/HOTFIXES.md: 기존 2026-05-21 typedef 항목의 Status / Next step
을 v0.17.0 closure 표현으로 갱신 (관찰 기록은 frozen 유지).
- tasks/p10/p10-1d-c-cpp-ast-chunker.md: Risks 의 typedef idiom 라인
을 closure ✅ + 잔여 nested typedef 안내로 갱신.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
closure of HOTFIXES 2026-05-21. C typedef-wrapped anonymous
struct/enum/union 이 typedef alias 이름으로 symbol unit 방출.
- crates/kebab-parse-code/src/c.rs: type_definition 분기 추가.
inner anonymous struct_specifier / enum_specifier / union_specifier
탐지 → declarator field 의 type_identifier 재귀 추출 → synthetic
unit (typedef alias). named inner aggregate / plain alias 는
기존대로 glue. PARSER_VERSION code-c-v1 → code-c-v2.
recover_typedef_alias + extract_typedef_alias_name helper 추가.
- crates/kebab-store-sqlite/src/store.rs: 두 helper 신규
(parser_version bump cascade 용 doc-id 기반 orphan purge).
- stale_chunk_ids_for_workspace_path_except_doc_id(workspace_path,
keep_doc_id) — sister of stale_chunk_ids_at, doc_id 기반.
- purge_document_at_workspace_path_except_doc_id(workspace_path,
keep_doc_id) — CASCADE document/chunks 제거, assets 보존.
keep_doc_id="" 가 "모든 doc 제거" 사용.
- crates/kebab-app/src/lib.rs: try_skip_unchanged 의 parser_mismatch
분기에서 purge_workspace_path_for_parser_bump 호출. helper 가
app.vector() 로 lazy 접근 + delete_by_chunk_ids + SQLite document
row 제거. Ok(None) 반환 전 cleanup 끝나서 caller 의 새 INSERT 시
idx_docs_workspace_path UNIQUE 충돌 회피.
- tests:
- c.rs unit tests 4 신규 — typedef_struct_emits_unit /
typedef_enum_emits_unit / typedef_union_emits_unit /
typedef_to_existing_type_stays_glue (negative).
- tier1_c_ingest_searchable: parser_version assertion code-c-v1 →
code-c-v2.
- 회귀: bytes-edit 경로 (asset_id 변경) 의 기존 purge_orphan_at_workspace_path
+ purge_vector_orphans_for_workspace_path 는 그대로 — 신규 분기와
공존, 기존 test 모두 PASS.
미해결 (Risks): nested typedef (typedef struct { struct {...} inner; }
Outer;) 의 inner 익명 struct 는 여전히 glue — v2 의 1차 범위는
top-level typedef alias 만.
cargo test --workspace --no-fail-fast -j 1 + clippy 통과.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
