feat: ingest_doc 확인 루프 — confirm_ingest 툴 추가 및 OkfBundle 연동

[thrcle]

#️⃣ Issue Number

없음

📝 요약(Summary)

한 줄 요약: 문서에서 뽑은 비즈니스 용어 후보를 사용자가 검토·승인하면 시멘틱 레이어에 자동 등록되는 확인 루프를 추가합니다.

해결하려는 문제

기존 ingest_doc은 문서에서 용어 후보를 추출해 텍스트로만 보여줬습니다. 사용자가 "좋아 보여"라고 해도 실제로 저장되는 건 없었습니다. 확인 단계와 저장 단계 사이의 연결고리가 없는 상태였습니다.

ingest_doc.py 원문 주석: "V1 does NOT auto-register — confirmation is a frontend step (Week 4)"

이번 변경으로 달라지는 것

2단계 확인 루프가 완성됩니다.

Step 1 — 문서 업로드 및 후보 추출

사용자: /ingest ref:defs.md

시스템: Proposed definitions from 'defs.md':
  1. [METRIC] monthly_revenue [orders] — SUM(orders.amount)
  2. [RULE]   exclude_cancelled — status != 'cancelled'
  3. [DIMENSION] customer_tier — users.tier

  → confirm_ingest(ref='defs.md', accept='all')로 전체 등록,
    또는 accept='1,3'처럼 번호로 선택 등록 가능합니다.

후보는 KV에 pending_ingest:defs.md 키로 임시 보관됩니다.

Step 2 — 확인 및 등록

사용자: /confirm_ingest ref:defs.md accept:1,3 layer:guild

시스템: ✅ 2 term(s) registered to [guild]:
  - [METRIC] monthly_revenue
  - [DIMENSION] customer_tier

confirm 시점에 FedEntry로 변환되어 KV에 저장됩니다.

OkfBundle 연동 (PR2와의 연결)

OKF_BUNDLE_DIR 환경변수를 설정하면 confirm 후 자동으로 OkfBundle로도 내보냅니다. 설정하지 않으면 KV 저장만 합니다.

OKF_BUNDLE_DIR=./knowledge_bundle lang2sql-bot

다음 PR과의 관계

PR1 (FedEntry kind 필드) → PR2 (OKF bundle 어댑터) → PR3 (이 PR) → PR4 (disambiguation 개선)

PR4에서는 등록된 kind 정보를 system prompt에 주입해 SQL 생성 정확도를 높입니다.

💬 To Reviewers

이 PR은 총 4개로 구성된 시리즈의 세 번째입니다. PR2 머지 후 순차 머지 부탁드립니다.

• pending_ingest:{ref} 키의 TTL(만료) 처리는 v1.5에서 논의할 수 있습니다. 현재는 만료 없이 KV에 남아 있습니다.
• accept 파라미터로 인덱스 선택 외에 용어명 직접 지정 방식도 고려했으나, 인덱스 방식이 LLM 툴콜 관점에서 더 간결하다고 판단했습니다.

PR Checklist

• 변경 사항에 대한 테스트 또는 검증 완료 (신규 테스트 14개: 직렬화, 선택 로직, KV 저장, OkfBundle 연동, 레지스트리)
• 로컬에서 정상 동작 확인 (147 passed)
• 관련 문서 업데이트 완료

[thrcle]

수정 사항 정리

리뷰 감사합니다. 아래 내용을 반영해 feat/confirm-ingest-loop 브랜치에 추가 커밋했습니다.

confirm_ingest — 검증 로직 보강

define에 있던 layer 검증 블록을 _validate_layer 공통 함수로 추출하고, confirm_ingest에도 동일하게 적용했습니다.

• layer 정규화: 대소문자 구분 없이 처리 ("Guild" → "guild")
• guild 레이어 권한 검사: is_admin 미충족 시 등록 거부
• 빈 channel_id 가드: channel 레이어 요청 시 channel_id 없으면 거부

okf_bundle — 경로 안전성 및 파싱 버그 수정

• Path traversal 차단: slug 생성 시 /, \ 제거 + is_relative_to(base_dir) 검증 추가. 검증 실패 항목은 export 루프에서 skip 처리
• frontmatter 파싱 수정: text.index("---", 3) → text[4:].split("\n---\n", 1) 방식으로 변경해 definition 본문에 ---가 포함된 경우에도 정상 파싱

테스트 추가

• test_confirm_guild_layer_blocked_for_non_admin
• test_confirm_channel_layer_blocked_without_channel_id
• test_confirm_invalid_layer_returns_error

---

머지 순서: PR2(#242) → PR3(#243) → PR4(#244) 순서로 머지 부탁드립니다.

[seyoung4503]

머지 가능합니다. 테스트 151개 통과.

수정 확인했습니다 — 비관리자 전사 등록 거부, 빈 채널 ID 거부, "Guild" 같은 값 정규화, 정의에 --- 들어가도 유실 없음. _validate_layer로 검증을 한 곳에 모으신 것 좋습니다.

로컬 .venv에 PyYAML이 없어서 uv sync 하셔야 테스트가 돕니다.

[seyoung4503]

👍 좋습니다!!