doc-reorg(C) Phase 4a: 둘 다 심하게 stale(HANDOFF "한 줄 요약" v0.18.0 ·
이미 ship 된 fb-41 을 "미구현"으로 · v0.20 priorities 장기 closed; INDEX 는
삭제될 task spec 으로 82 markdown 링크 + 옛 버전 스탬프).
- HANDOFF 181→45줄: 현재 phase 표(흡수된 crate 반영) + 최근 마일스톤 포인터
(dated 로그는 HOTFIXES/CHANGELOG/git) + 현재 다음-task 후보(P8/P9-5).
- INDEX 185→40줄: per-component 상태 표(spec 링크 제거) + HOTFIXES/CHANGELOG/
설계계약 포인터. 옛 task spec 은 git history 안내.
durable 정보 손실 0(전부 HOTFIXES/CHANGELOG/ARCHITECTURE/code/git 에 있음).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
여러 세션 누적으로 ~268개로 불어난 문서를 3 병렬 explorer 로 전수 특성화한 뒤
재정리 설계. 코어(living+frozen)는 건강하고 SoT 도 territory 별로 정의돼 있으나
단일 지도 부재 + historical 아티팩트(plans 64·handoffs 8) 가 트리에 섞임.
설계(방안 B): 3구역 분리(living/frozen/archive) + root DOCS.md SoT 지도 신설 +
오펀 stub 7 삭제 + release-notes 9→CHANGELOG.md 통합 + historical 을
docs/archive/ 로 git mv + stale 컴포넌트 README 2건 수정 + CLAUDE.md §docs 갱신.
frozen specs/tasks 는 거버넌스 앵커라 무변경(이동 전 frozen→대상 링크 grep gate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
최신 코드베이스 기준으로 사용자/아키텍처 문서 갱신:
README (사용자 설명서 수준):
- 버전 스탬프 v0.21.0 → v0.32.0 (2곳)
- 파생물 캐시 설명에 OCR/caption 캐싱 반영 (embedding 만 → embedding+vision)
ARCHITECTURE (구조 상세):
- migrations V001..V014 → V015 (drop chat_sessions, v0.31.0)
- derivation_cache kind: "embedding 만 남음" → embedding + ocr + caption (#217)
- 9개 code_*_ast_v1.rs → 단일 code_ast_v1.rs / CodeAstV1Chunker (v0.32.0 #220) — dir tree + 결정표
- MCP 도구 목록 4개 → 8개 (schema/doctor/search/bulk_search/ask/fetch/ingest_file/ingest_stdin)
- stale /build/dogfood 경로 → 실 경로/HOTFIXES 참조
CLAUDE.md:
- "README 최신성 hard requirement" 명문화 — 기능 추가/변경/삭제·사용자 표면 변경 시
그 PR 에서 README 동기화, 제거된 surface 는 README 에서도 제거. 단 깊이는
"사용자 설명서" 수준이고 아키텍처는 docs/ARCHITECTURE.md 에 — altitude 경계 명시.
- stale TUI bullet 정정 (kebab tui 는 v0.31.0 제거 → CLI 가 유일 UI surface)
code: derivation.rs 모듈 주석의 kind 목록 {embedding,alias,korean_tokens} →
{embedding,ocr,caption} (source-of-truth 주석 정정).
독립 doc-accuracy 감사로 config 기본값(llm/embedding/rag/chunker/ocr)·CLI 표면·
crate 목록·migration·cache kind 전수 대조 — 위 2건 외 잔여 staleness 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
리뷰어가 잡은 release-doc 사실 오류 정정:
- dep −2 → dep −1: serde_yaml_ng 0.10 도 unsafe-libyaml 0.2.11 을 transitive 로
의존(Cargo.lock 확인). 제거된 건 archived serde_yaml 하나뿐. "unsafe-libyaml
까지 제거" 는 거짓 → 4곳(release notes ×2, Cargo.toml, HOTFIXES) 정정.
- crate 24→20 → 22→20: 이 arc(#219–#222)는 #221 에서 2 crate(kebab-embed/llm)만
제거. 24→22 는 직전 v0.31.0 spine. cumulative 표기는 명시적 주석으로 분리.
- 누적 줄수 약 −3200 → 약 −3400(실측 git diff fd3b4ae..main = 643 ins/4057 del).
코드 변경 없음(release-facing 문서 + 버전 주석). Cargo.toml 파싱 OK.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
리뷰 nit: dropped serde_yaml 은 workspace-pinned 였는데 대체 serde_yaml_ng 가
3 crate 에 개별 "0.10" 하드코딩이라 single-version-pin invariant 깨짐.
`[workspace.dependencies]` 에 serde_yaml_ng = "0.10" 추가 + kebab-chunk/eval/
parse-md(사전존재 하드코딩 포함) 를 { workspace = true } 로 통일 — 워크스페이스의
다른 공유 dep 과 동일 컨벤션. 빌드 dep resolution 불변(0.10.0 단일).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
ponytail-audit 의 작은 over-engineering 잔여 3건 (output/동작 불변):
1. FusionPolicy 1-arm enum 제거 — kebab-search 내부 전용(외부 importer 0)이던
`enum FusionPolicy { Rrf { k_rrf } }` 를 `HybridRetriever.k_rrf: u32` 로 inline.
parse_fusion 은 u32 반환. RRF 수식 `Σ 1/(k_rrf+rank)` byte-identical.
2. dual YAML 통일 — serde_yaml(0.9) 를 maintained fork serde_yaml_ng(0.10) 로 일원화.
k8s manifest chunker + eval golden loader 2 site 마이그레이션(API drop-in),
workspace dep 에서 serde_yaml 제거. parse 결과 불변.
3. NliVerifier::hypothesis_token_count 의 `Ok(0)` default 제거 → required.
prod OnnxNliVerifier 가 이미 override 라 동작 불변, MockNliVerifier 에 explicit 추가.
문서 동기화: search/eval/parse component README + ARCHITECTURE 의 FusionPolicy/
serde_yaml 참조를 현 상태로 갱신. net −37줄. 적대적 검증 2렌즈(output-identity +
completeness-build) 통과, 영향 crate 테스트 + clippy -D warnings 클린.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
kebab-embed/kebab-llm 은 "새 type 없음"을 자처한 순수 re-export 셸이었다
(trait 은 이미 kebab-core 소유, mock + test helper 만 보유). "kebab-core
재구성 시 안정 surface" 라는 명분은 1인 RAG 엔 speculative YAGNI. 흡수:
- kebab-core 에 default-OFF `mock` feature + src/mock.rs (MockEmbedder,
MockLanguageModel, assert_vector_shape/assert_unit_norm/assert_finish_chunk
을 kebab_core:: → crate:: import 만 바꿔 verbatim 이동).
- production import 2곳(kebab-embed-local, kebab-llm-local) +
test import 다수(search/rag/parse-image/embed-local) 를 kebab_core 로 repoint.
mock 쓰는 crate 는 dev-dep 에 features=["mock"] (default 빌드 무영향).
- shim 자체 테스트: mock 동작 테스트는 kebab-core/tests/ 로 이동,
reexports.rs(셸 재수출 테스트)는 폐기.
- crates/kebab-embed, crates/kebab-llm 삭제 + workspace member/deps 정리.
- ARCHITECTURE/HANDOFF/component README 의 crate 그래프·표·rationale 갱신
(22 → 20 crates). llm-local 의 broken intra-doc link 2건도 정리.
trait surface·동작 불변 (test-only + import-rename). workspace build 는 mock
default-OFF 라 mock 코드 미컴파일. 적대적 검증 3렌즈(build-test-integrity +
behavior-identity[mock byte-identical] + dead-crate-completeness) 통과,
clippy --workspace -D warnings 클린.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
리뷰 nit: collapsed AST chunk arm 의 .context(format!(...)) 는 성공 경로에서도
String 을 매번 할당. .with_context(|| format!(...)) 로 에러 경로에만 alloc.
(나머지 nit — 일반화된 error-text "CodeAstV1Chunker" — 은 리뷰어가 no-action:
테스트가 새 substring 으로 맞춰져 있고 7개 arm 과 .context prefix 통일됨.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
code_{c,cpp,go,java,js,kotlin,python,rust,ts}_ast_v1.rs 9개는 struct 이름과
const VERSION_LABEL 문자열만 다른 byte-identical 복붙이었다 (chunker 는
tree-sitter 를 안 쓰고 lang 은 SourceSpan::Code 데이터에서 흘러나옴). 하나로
통합:
- 신규 CodeAstV1Chunker { version_label: &'static str } + for_lang(lang) 생성자.
9개 lang → 기존 VERSION_LABEL 문자열을 verbatim 매핑 (rust→code-rust-ast-v1,
typescript→code-ts-ast-v1, javascript→code-js-ast-v1, ...). chunker_version()
이 라벨을 그대로 반환 → chunk_id (id_for_chunk) byte-identical → 재인덱싱·
버전 캐스케이드 0.
- chunk/policy_hash/make_chunk/split_oversize 는 code_rust_ast_v1.rs 에서 verbatim
이식. 인라인 유닛 테스트 1세트 + 9-lang 라벨 매핑 테스트 추가.
- 9개 src 파일 삭제, lib.rs 9 mod+pub use → 1.
- ingest.rs 의 두 디스패치(chunker_version 스탬프 ~2700 + .chunk() ~3298)에서
9개 AST arm 을 단일 arm 으로 collapse, for_lang(code_lang) 사용. 비-AST
chunker(K8s/Dockerfile/Manifest/TextParagraph) arm 은 무손상.
byte-identical 증명: 9개 골든 스냅샷 테스트(tests/code_*_ast_snapshot.rs)가
assertion/expected-data 수정 0으로 통과 — construction/import 줄만 변경.
net −3030줄 (20파일 +143/−3173). 적대적 검증 3렌즈(byte-identical-proof +
version-string-integrity[9 라벨 old==new] + completeness) 통과, clippy -D warnings 클린.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
in-process LRU search cache 는 spine 재작성(#214)에서 이미 삭제됐는데
그 비계(scaffold)만 남아 있었다. 잔존물 제거:
- App::search/search_uncached 붕괴 (search() 는 1줄 위임자였음)
- search_uncached_with_config facade + 그 테스트 삭제
- 죽은 `search --no-cache` / `search --explain` CLI 플래그 제거
(ask --explain 은 live — 건드리지 않음)
- 안 읽히던 RagCfg.explain_default config 필드 + fixture 제거
- 제거된 표면을 가리키던 stale 주석/문서(citation_helper/hybrid/
search·app-facade README/DOGFOOD/HANDOFF) 정정
코어 검색 출력은 byte-identical (search_uncached 본문이 search() 로
verbatim 이동). `search_cache: false` wire capability 는 유지 — 제거 시
schema.v1 breaking bump 이라 손해. 적대적 검증 2렌즈(correctness-preserved
+ wire/config-safe) 통과, dead-symbol-complete 가 잡은 5건 주석/문서 정정 완료.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La
(a) embed_with_cache 를 image/pdf/code 핸들러에 배선(markdown 전용→전미디어) — PR1.
(b) ocr/caption derivation_cache 네임스페이스로 OCR/caption 중간 산출물 캐싱 —
버전-캐스케이드 분리 + ollama-vision 비결정성 박제 — PR2.
리서치로 해소: provenance 는 wire/게이트에 없어 캐시 히트 시 재현 불필요(byte-identical
유지) · payload 는 full 구조체 serde(block 레벨까지 byte-identical) · derivation_cache_key_bytes
신설 · paddle ONNX 자산은 이미 레포 번들(다운로드 불필요) → 결정적 게이트 가능.
열린 항목: paddle 게이트용 text-bearing OCR 코퍼스 생성(R2, plan 에서 해소).
endpoint/det_model/rec_model/dict 는 default None 이라 reconcile 가 pdf 블록에
채우지 않는다(None 은 annotated-default 에서 누락). image 만 설정한 이 키를 공유
[ingest.ocr] 로 끌어올리면 resolve_ocr overlay 가 (medium_has(pdf,key)=false 라)
pdf 로 누출돼, pdf OCR endpoint/asset 경로가 v4 와 달라지고 det/rec/dict 는
ingest_config_signature 에 들어가 강제 재색인까지 유발했다. step_4_to_5 에서
Option 키는 pdf 도 명시한 경우에만 hoist 하도록 OPTION_OCR_KEYS 가드 추가.
기존 round-trip 테스트는 before=Config::from_file(v4) 가 이미 마이그레이션+resolve
를 거친 오염값이라 after==before tautology 였음 — pdf.det_model==None 명시 검증
추가 + 비대칭 image-only-endpoint 회귀 테스트 신설.
