altair823-org/kebab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

docs: mark P0–P4 done, add SMOKE recipe, refresh README #26

Merged
altair823 merged 1 commits from docs/post-p4-doc-updates into main 2026-05-01 16:37:45 +00:00
Conversation 1 Commits 1 Files Changed 24 +245 -75
altair823 commented 2026-05-01 16:33:01 +00:00
Owner
Copy Link

변경 요약

P0–P4 완료 + 3건 post-merge hotfix 적용 후 누적된 문서 drift 정리. 코드 변경 0 — pure docs sweep.

무엇을 했는가

README.md 새로 씀

  • 최상단 status banner: "spec 동결, 코드 0줄" → "P0–P4 완료 (17/31 task) + 3 hotfix".
  • Command 테이블: 각 명령에 owning phase + 현재 상태 표시 (kb ingest ✅ P3-5, kb ask ✅ P4-3, kb eval ⏳ P5 등).
  • Phase 로드맵 테이블에 Status 컬럼 추가 — P0P4 ✅ 완료, P5 ⏳ 다음, P6P9 ⏳ pending.
  • Component 개수 30 → 31 (P3-5 app-wiring 추가 반영).
  • 핵심 결정 테이블에 RRF [0, 1] 정규화 invariant 추가.
  • 빌드+실행 섹션에서 "P0 미시작" 경고 제거 — 이제 실제 동작.
  • HOTFIXES.md / SMOKE.md cross-link 추가.
  • 기여 흐름에 post-merge 핫픽스 절차 항목 추가 (HOTFIXES.md 에 dated entry + 영향 받는 task spec 의 Risks/notes 한 줄).

docs/SMOKE.md 신규

직접 워크스페이스 격리 실행 절차. 사용자 환경 (~/.config/kb/, ~/.local/share/kb/)을 안 건드리고 /tmp/kb-smoke/ 같은 임시 디렉토리에 KB 띄우는 패턴:

  • 빌드 + 원격 Ollama 노출 절차.
  • 격리된 워크스페이스 + config.toml 시드 (post-merge default 적용된 형태).
  • 명령 시퀀스 9개 (doctor → ingest → list → search × 3 modes → inspect → ask × 2).
  • 검증 체크리스트 (fusion_score [0,1], --config honor, marker: \"[1]\" 형식 등).
  • 알려진 동작 (470MB fastembed 다운로드, ask 응답 시간 20-55s, --config malformed 시 hard-fail).
  • 정리 절차.

Phase + task spec status frontmatter 일괄 갱신

status: planned → status: completed 변경:

  • tasks/phase-{0,1,2,3,4}-*.md (5개)
  • tasks/p0/p0-1-*.md, tasks/p1/*.md (6), tasks/p2/*.md (2), tasks/p3/*.md (5), tasks/p4/*.md (3) — 합계 17개 component task.
  • P5~P9 phase docs + task specs는 planned 그대로.

변경 파일

  • README.md (전면 수정)
  • docs/SMOKE.md (신규)
  • tasks/phase-{0..4}-*.md (5)
  • tasks/p[0-4]/*.md (17)

검증

cargo test --workspace → 319 passed / 0 failed. clippy clean (소스 변경 없음). 문서만 변경되었으므로 회귀 위험 0.

후속

P5-1 진입 가능. eval framework 구현 시 tasks/p5/ 의 status: planned 도 그때 갱신.

## 변경 요약 P0–P4 완료 + 3건 post-merge hotfix 적용 후 누적된 문서 drift 정리. 코드 변경 0 — pure docs sweep. ## 무엇을 했는가 ### `README.md` 새로 씀 - 최상단 status banner: \"spec 동결, 코드 0줄\" → \"P0–P4 완료 (17/31 task) + 3 hotfix\". - Command 테이블: 각 명령에 owning phase + 현재 상태 표시 (`kb ingest` ✅ P3-5, `kb ask` ✅ P4-3, `kb eval` ⏳ P5 등). - Phase 로드맵 테이블에 **Status 컬럼** 추가 — P0~P4 ✅ 완료, P5 ⏳ 다음, P6~P9 ⏳ pending. - Component 개수 30 → 31 (P3-5 app-wiring 추가 반영). - 핵심 결정 테이블에 RRF [0, 1] 정규화 invariant 추가. - 빌드+실행 섹션에서 \"P0 미시작\" 경고 제거 — 이제 실제 동작. - HOTFIXES.md / SMOKE.md cross-link 추가. - 기여 흐름에 post-merge 핫픽스 절차 항목 추가 (HOTFIXES.md 에 dated entry + 영향 받는 task spec 의 Risks/notes 한 줄). ### `docs/SMOKE.md` 신규 직접 워크스페이스 격리 실행 절차. 사용자 환경 (`~/.config/kb/`, `~/.local/share/kb/`)을 안 건드리고 `/tmp/kb-smoke/` 같은 임시 디렉토리에 KB 띄우는 패턴: - 빌드 + 원격 Ollama 노출 절차. - 격리된 워크스페이스 + config.toml 시드 (post-merge default 적용된 형태). - 명령 시퀀스 9개 (`doctor` → `ingest` → `list` → `search` × 3 modes → `inspect` → `ask` × 2). - 검증 체크리스트 (fusion_score [0,1], `--config` honor, `marker: \"[1]\"` 형식 등). - 알려진 동작 (470MB fastembed 다운로드, ask 응답 시간 20-55s, `--config` malformed 시 hard-fail). - 정리 절차. ### Phase + task spec status frontmatter 일괄 갱신 `status: planned` → `status: completed` 변경: - `tasks/phase-{0,1,2,3,4}-*.md` (5개) - `tasks/p0/p0-1-*.md`, `tasks/p1/*.md` (6), `tasks/p2/*.md` (2), `tasks/p3/*.md` (5), `tasks/p4/*.md` (3) — 합계 17개 component task. - P5~P9 phase docs + task specs는 `planned` 그대로. ## 변경 파일 - `README.md` (전면 수정) - `docs/SMOKE.md` (신규) - `tasks/phase-{0..4}-*.md` (5) - `tasks/p[0-4]/*.md` (17) ## 검증 `cargo test --workspace` → 319 passed / 0 failed. clippy clean (소스 변경 없음). 문서만 변경되었으므로 회귀 위험 0. ## 후속 P5-1 진입 가능. eval framework 구현 시 `tasks/p5/` 의 `status: planned` 도 그때 갱신.
altair823 added 1 commit 2026-05-01 16:33:02 +00:00
docs: mark P0–P4 done, add SMOKE recipe, refresh README d1b99b2994 
State drift after P0–P4 completion + 3 post-merge hotfixes (PR #20
--config across subcommands, PR #24 --config in kb ask, PR #25 RRF
fusion_score normalization). README still framed the project as
"spec frozen, code 0 lines"; phase docs and task specs all carried
status: planned. Sweep:

- README.md: top banner now "P0–P4 done (17/31 tasks) + 3 hotfixes
  applied"; command table marks each subcommand's owning phase and
  current status (kb ask = ✅ via P4-3, kb eval = ⏳ P5);
  phase roadmap table grew a Status column (P0–P4 completed, P5
  next, P6–P9 pending); component count bumped 30 → 31 to reflect
  P3-5 (app-wiring, post-spec); core decisions table notes the
  RRF [0,1] normalization invariant; build+실행 section drops the
  "P0 미시작" caveat; new pointers to HOTFIXES.md and SMOKE.md.
- docs/SMOKE.md (new): ~80-line recipe for running the full
  pipeline against an isolated /tmp/kb-smoke/ workspace via
  --config, without polluting ~/.config/kb/ or
  ~/.local/share/kb/. Covers fixture seeding, sample config.toml
  with the post-merge defaults, doctor → ingest → list →
  search × 3 modes → inspect → ask sequence, verification
  checklist, and known-behaviour notes (fastembed model
  download, RAG response time, --config hard-fail on missing
  path).
- tasks/phase-{0..4}-*.md: status frontmatter flipped planned →
  completed.
- tasks/p0/, tasks/p1/, tasks/p2/, tasks/p3/, tasks/p4/: same
  status flip across all 17 component task specs (1+6+2+5+3).
  P5–P9 stay planned.

cargo test --workspace: 319 passed; clippy clean (no source
changes in this commit, just docs + frontmatter).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
claude-reviewer-01 reviewed 2026-05-01 16:33:32 +00:00
claude-reviewer-01 left a comment
Member
Copy Link

P0–P4 완료 + 3건 post-merge hotfix 후 누적된 문서 drift 정리 PR 코드 리뷰 — 셀프 머지 게이트로 인해 COMMENT only.

코드 변경 0 — pure docs sweep. 회귀 위험 0. 워크스페이스 319 tests pass, clippy clean (이전 상태 그대로).

핵심:

  1. README.md 전면 수정 — 최상단 status banner가 실제 진척 상태 surface, command 테이블 + phase 로드맵에 status 컬럼 추가, RRF [0,1] 정규화 invariant 명문화, HOTFIXES.md / SMOKE.md cross-link.
  2. docs/SMOKE.md 신규 — isolated /tmp 워크스페이스 + --config 패턴으로 사용자 환경 안 건드리고 전체 파이프라인 검증하는 recipe. fixture 시드 + config.toml + 9-step 명령 시퀀스 + 검증 체크리스트 + 알려진 동작 모두 포함.
  3. 22개 phase / task spec status frontmatter 일괄 갱신 (planned → completed for P0–P4). P5–P9 그대로.

INDEX.md / README.md / phase docs / task spec frontmatter 4개 레이어가 이제 일관되게 "P0–P4 완료" 상태를 보여줌. 누적 drift 닫힘.

inline 코멘트는 모두 결정에 대한 노트입니다. 머지 진행해도 됩니다. 다음은 P5-1 golden-fixture-runner.

P0–P4 완료 + 3건 post-merge hotfix 후 누적된 문서 drift 정리 PR 코드 리뷰 — 셀프 머지 게이트로 인해 COMMENT only. 코드 변경 0 — pure docs sweep. 회귀 위험 0. 워크스페이스 319 tests pass, clippy clean (이전 상태 그대로). 핵심: 1. **README.md 전면 수정** — 최상단 status banner가 실제 진척 상태 surface, command 테이블 + phase 로드맵에 status 컬럼 추가, RRF [0,1] 정규화 invariant 명문화, HOTFIXES.md / SMOKE.md cross-link. 2. **docs/SMOKE.md 신규** — isolated /tmp 워크스페이스 + --config 패턴으로 사용자 환경 안 건드리고 전체 파이프라인 검증하는 recipe. fixture 시드 + config.toml + 9-step 명령 시퀀스 + 검증 체크리스트 + 알려진 동작 모두 포함. 3. **22개 phase / task spec status frontmatter** 일괄 갱신 (planned → completed for P0–P4). P5–P9 그대로. INDEX.md / README.md / phase docs / task spec frontmatter 4개 레이어가 이제 일관되게 \"P0–P4 완료\" 상태를 보여줌. 누적 drift 닫힘. inline 코멘트는 모두 결정에 대한 노트입니다. 머지 진행해도 됩니다. 다음은 P5-1 golden-fixture-runner.
README.md
@@ -1,6 +1,6 @@
# kb — Local-first Knowledge Base
> **상태:** spec 동결 단계. 코드 0줄. 30 component task spec 모두 작성/리뷰/머지 완료. 다음 단계 = P0 구현.
> **상태:** P0–P4 구현 완료 (31 component task 중 17 완료) + 3건 post-merge hotfix 적용. `kb index` / `kb search --mode {lexical,vector,hybrid}` / `kb ask` 모두 실 동작. 다음 단계 = P5 (eval suite). 자세한 진행 상황은 [tasks/INDEX.md](tasks/INDEX.md), 머지 후 발견된 버그와 fix는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md).
claude-reviewer-01 commented 2026-05-01 16:33:32 +00:00
Member
Copy Link

최상단 status banner가 진정 의미를 갖게 됨 — 누적된 "spec 동결, 코드 0줄" framing 이 P0–P4 머지 시점에 거짓이 된 상태였음. 이제 실제 진척 상태 (17/31 task + 3 hotfix) + 다음 milestone (P5) + 빠진 reference (HOTFIXES.md) 모두 surface. 이 repo를 처음 보는 reader 가 30초 안에 정확한 상태 파악 가능.

최상단 status banner가 진정 의미를 갖게 됨 — 누적된 "spec 동결, 코드 0줄" framing 이 P0–P4 머지 시점에 거짓이 된 상태였음. 이제 실제 진척 상태 (17/31 task + 3 hotfix) + 다음 milestone (P5) + 빠진 reference (HOTFIXES.md) 모두 surface. 이 repo를 처음 보는 reader 가 30초 안에 정확한 상태 파악 가능.
README.md
@@ -75,4 +77,4 @@
---
## Phase 로드맵
claude-reviewer-01 commented 2026-05-01 16:33:32 +00:00
Member
Copy Link

Phase 로드맵 테이블의 Status 컬럼 신규 — 이전엔 phase 모두 동일한 텍스트라 reader가 "어디까지 됐지?"를 알 수 없었음. 이제 P0P4 ✅ 완료 / P5 ⏳ 다음 / P6P9 ⏳ 가 시각적으로 분리. P+ 에서 이 테이블을 update 하는 사람도 한 컬럼만 손대면 됨.

Phase 로드맵 테이블의 Status 컬럼 신규 — 이전엔 phase 모두 동일한 텍스트라 reader가 "어디까지 됐지?"를 알 수 없었음. 이제 P0~P4 ✅ 완료 / P5 ⏳ 다음 / P6~P9 ⏳ 가 시각적으로 분리. P+ 에서 이 테이블을 update 하는 사람도 한 컬럼만 손대면 됨.
docs/SMOKE.md
@@ -0,0 +1,158 @@
---
claude-reviewer-01 commented 2026-05-01 16:33:32 +00:00
Member
Copy Link

isolated /tmp 워크스페이스 + --config 패턴 절차 명문화. 사용자 환경 (~/.config/kb/, ~/.local/share/kb/) 을 한 번도 건드리지 않고 전체 파이프라인 검증 가능. P5+ 진입 시점에 회귀 검증, 또는 외부 contributor 의 first-touch experience 양쪽에서 useful. P3-5 hotfix 이후 --config flag 가 정확히 honor 되는 점 + RRF [0,1] 정규화 이후 default score_gate=0.05 가 동작하는 점이 recipe 안에 자연스럽게 녹아있음.

isolated /tmp 워크스페이스 + --config 패턴 절차 명문화. 사용자 환경 (~/.config/kb/, ~/.local/share/kb/) 을 한 번도 건드리지 않고 전체 파이프라인 검증 가능. P5+ 진입 시점에 회귀 검증, 또는 외부 contributor 의 first-touch experience 양쪽에서 useful. P3-5 hotfix 이후 --config flag 가 정확히 honor 되는 점 + RRF [0,1] 정규화 이후 default score_gate=0.05 가 동작하는 점이 recipe 안에 자연스럽게 녹아있음.
tasks/p3/p3-5-app-wiring.md
@@ -4,3 +4,3 @@
task_id: p3-5
title: "Wire kb-app facade — ingest / search / list / inspect end-to-end"
status: planned
status: completed
claude-reviewer-01 commented 2026-05-01 16:33:32 +00:00
Member
Copy Link

P3-5 (app-wiring) 도 정식 task로 component 개수 31에 포함. P0~P4 시점 spec 작성 당시 30이었지만 P3-5는 후속 추가 task — 이번 README 업데이트로 그 history 가 명문화됨.

P3-5 (app-wiring) 도 정식 task로 component 개수 31에 포함. P0~P4 시점 spec 작성 당시 30이었지만 P3-5는 후속 추가 task — 이번 README 업데이트로 그 history 가 명문화됨.
tasks/phase-3-vector-hybrid.md
@@ -2,3 +2,3 @@
phase: P3
title: "Local embedding + LanceDB + hybrid search"
status: planned
status: completed
claude-reviewer-01 commented 2026-05-01 16:33:32 +00:00
Member
Copy Link

phase frontmatter status flip planned → completed. 단순 mechanical 변경이지만 INDEX.md 의 phase 표 + README 의 phase 로드맵 + 이 doc 의 frontmatter 가 이제 모두 일관됨 — 누적 drift 닫힘.

phase frontmatter status flip planned → completed. 단순 mechanical 변경이지만 INDEX.md 의 phase 표 + README 의 phase 로드맵 + 이 doc 의 frontmatter 가 이제 모두 일관됨 — 누적 drift 닫힘.
altair823 merged commit 2c0607ae95 into main 2026-05-01 16:37:45 +00:00
altair823 deleted branch docs/post-p4-doc-updates 2026-05-01 16:37:46 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
claude-reviewer-01
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
altair823 claude-reviewer-01
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: altair823-org/kebab#26
Delete Branch "docs/post-p4-doc-updates"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?