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

docs: 재조정 후속 — 정책 문구 정합 + 코드 코멘트 lag 수정

Browse Source 
spec 재조정(이전 commit)으로 생긴 정책↔실제 모순 + 검증이 발견한 코드 lag 정리.

- CLAUDE.md / DOCS.md: "frozen 편집 금지" → "reconciled baseline" 으로 정합.
  원칙 동결이되, 누적 drift/삭제로 문서가 현실과 모순되면 주기적 dated 재조정
  (✂/⟳/⚠)을 허용·기대. HOTFIXES 는 재조정 사이 fine-grained live deviation log.
- kebab-rag/src/pipeline.rs:580: doc-comment rag-multi-hop-v1 → v2
  (실제 const PROMPT_TEMPLATE_VERSION_MULTI_HOP 와 일치 — 검증 패스 발견).

코멘트 전용 변경이라 빌드 영향 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C5r6DDehC3ECcC2BxLsPHu
This commit is contained in:
altair823
2026-06-27 23:09:28 +00:00
parent 6105ae1073
commit 93e69c9bec
3 changed files with 7 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CLAUDE.md
View File

@@ -8,7 +8,7 @@ Single-user local-first knowledge base + RAG. Rust 2024 workspace, 20 crates, si
The repo's documentation is split by audience + zone — don't duplicate across them. **[DOCS.md](DOCS.md)** is the doc map (what's the Source-of-Truth for what); start there if unsure where something belongs. The repo's documentation is split by audience + zone — don't duplicate across them. **[DOCS.md](DOCS.md)** is the doc map (what's the Source-of-Truth for what); start there if unsure where something belongs.
**zones**: *living* (현재 진실, 갱신 필수) · *frozen 계약* (설계 의도 baseline, 편집 금지 — `docs/superpowers/specs/2026-04-27-…-design.md` 하나) · *증거* (rust_report, dogfood/v0.18.0). 그 외 historical 문서(옛 plans/handoffs/task specs/feature specs)는 2026-06-27 doc-reorg 에서 삭제 — git history 에만. **새 plan/handoff/per-feature spec 문서를 쌓지 않는다**(그게 268개로 불어난 원인): 결정·deviation 은 HOTFIXES, 구조·불변식은 ARCHITECTURE, 릴리스는 CHANGELOG 에 직접. **zones**: *living* (현재 진실, 갱신 필수) · *설계 계약* (설계 의도 baseline — `docs/superpowers/specs/2026-04-27-…-design.md` 하나; 원칙 동결이되 코드와 크게 어긋나면 **dated 재조정 주석**(✂제거/⟳갱신/⚠모순수정)으로 정합, 2026-06-27 재조정 선례) · *증거* (rust_report, dogfood/v0.18.0). 그 외 historical 문서(옛 plans/handoffs/task specs/feature specs)는 2026-06-27 doc-reorg 에서 삭제 — git history 에만. **새 plan/handoff/per-feature spec 문서를 쌓지 않는다**(그게 268개로 불어난 원인): 결정·deviation 은 HOTFIXES, 구조·불변식은 ARCHITECTURE, 릴리스는 CHANGELOG 에 직접.
- **[README.md](README.md)** — first stop for an end user. Quick start, command table, one Mermaid logical-architecture diagram, configuration pointers, license. Stays narrow. (living) - **[README.md](README.md)** — first stop for an end user. Quick start, command table, one Mermaid logical-architecture diagram, configuration pointers, license. Stays narrow. (living)
- **[DOCS.md](DOCS.md)** — 문서 지도 / Source-of-Truth 인덱스. "어느 문서가 현재 진실인지" 한눈에. (living) - **[DOCS.md](DOCS.md)** — 문서 지도 / Source-of-Truth 인덱스. "어느 문서가 현재 진실인지" 한눈에. (living)
@@ -42,9 +42,9 @@ The dev/test profile is already trimmed (`debug = "line-tables-only"`, `split-de
## Spec contract ## Spec contract
`docs/superpowers/specs/2026-04-27-kebab-final-form-design.md` (12 sections) is the **single frozen design contract** for the whole workspace — "무엇을 의도했나"의 baseline. (The per-component task specs `tasks/p<N>/` + per-feature design specs that referenced it were removed in the 2026-06-27 doc-reorg; the shipped **code is the implementation truth**, the design contract is the intent baseline, and deviations live in HOTFIXES.) `docs/superpowers/specs/2026-04-27-kebab-final-form-design.md` (12 sections) is the **single frozen design contract** for the whole workspace — "무엇을 의도했나"의 baseline. (The per-component task specs `tasks/p<N>/` + per-feature design specs that referenced it were removed in the 2026-06-27 doc-reorg; the shipped **code is the implementation truth**, the design contract is the intent baseline (periodically dated-reconciled to current code — see the doc's 2026-06-27 banner), and live deviations live in HOTFIXES between reconciliations.)
- The design contract stays **frozen** — don't edit it retroactively to match what shipped. - The design contract is the intent **baseline**, kept stable — avoid free-form rewriting to chase every code change. BUT when accumulated drift/removals make it describe nonexistent features, a **periodic dated reconciliation pass** (✂ removed / ⟳ updated / ⚠ contradiction-fix — see the 2026-06-27 banner in the doc) is permitted and expected. HOTFIXES remains the fine-grained live deviation log between reconciliations.
- **Live deviations from the contract go in `tasks/HOTFIXES.md`** as dated entries. Treat HOTFIXES.md as the live source of truth when behavior and the contract disagree. Don't recreate per-feature spec/plan/handoff files — record decisions in HOTFIXES, structure/invariants in `docs/ARCHITECTURE.md`, releases in `CHANGELOG.md`. - **Live deviations from the contract go in `tasks/HOTFIXES.md`** as dated entries. Treat HOTFIXES.md as the live source of truth when behavior and the contract disagree. Don't recreate per-feature spec/plan/handoff files — record decisions in HOTFIXES, structure/invariants in `docs/ARCHITECTURE.md`, releases in `CHANGELOG.md`.
`tasks/INDEX.md` is the per-component status dashboard; `HANDOFF.md` is the phase-level dashboard. Update them when a component/phase status changes. The full doc map (what's the SoT for what) is **[DOCS.md](DOCS.md)**. `tasks/INDEX.md` is the per-component status dashboard; `HANDOFF.md` is the phase-level dashboard. Update them when a component/phase status changes. The full doc map (what's the SoT for what) is **[DOCS.md](DOCS.md)**.

6
DOCS.md
View File

@@ -1,6 +1,6 @@
# 📍 kebab 문서 지도 (Documentation Map / Source-of-Truth Index) # 📍 kebab 문서 지도 (Documentation Map / Source-of-Truth Index)
**현재 코드베이스의 진실 = 코드 + 아래 *living* 문서.** *계약* 은 "무엇을 의도했나"의 동결된 baseline, *증거* 는 과거 검증 기록이다. 그 외 historical 문서(옛 실행계획·task spec·feature spec·handoff)는 **git history 에만** 있다 — 2026-06-27 doc-reorg 에서 압축·삭제했고, durable 한 내용은 전부 아래 living 문서로 흡수했다. **현재 코드베이스의 진실 = 코드 + 아래 *living* 문서.** *계약* 은 "무엇을 의도했나"의 baseline(원칙 동결, 주기적 dated 재조정), *증거* 는 과거 검증 기록이다. 그 외 historical 문서(옛 실행계획·task spec·feature spec·handoff)는 **git history 에만** 있다 — 2026-06-27 doc-reorg 에서 압축·삭제했고, durable 한 내용은 전부 아래 living 문서로 흡수했다.
> 처음 보는 사람은 이 표 하나로 "어디를 봐야 현재 진실인지" 알 수 있다. 무엇이 최신인지 헷갈리면 여기부터. > 처음 보는 사람은 이 표 하나로 "어디를 봐야 현재 진실인지" 알 수 있다. 무엇이 최신인지 헷갈리면 여기부터.
@@ -19,14 +19,14 @@
| 격리 KB 로 직접 돌려보기 (smoke) | [docs/SMOKE.md](docs/SMOKE.md) | living | | 격리 KB 로 직접 돌려보기 (smoke) | [docs/SMOKE.md](docs/SMOKE.md) | living |
| 기능별 도그푸딩 시나리오 | [docs/DOGFOOD.md](docs/DOGFOOD.md) | living | | 기능별 도그푸딩 시나리오 | [docs/DOGFOOD.md](docs/DOGFOOD.md) | living |
| AI 코딩 에이전트 작업 규칙 | [CLAUDE.md](CLAUDE.md) | living | | AI 코딩 에이전트 작업 규칙 | [CLAUDE.md](CLAUDE.md) | living |
| 설계 원안 (12 섹션 계약) | [docs/superpowers/specs/2026-04-27-kebab-final-form-design.md](docs/superpowers/specs/2026-04-27-kebab-final-form-design.md) | **계약 (frozen)** | | 설계 원안 (12 섹션 계약) | [docs/superpowers/specs/2026-04-27-kebab-final-form-design.md](docs/superpowers/specs/2026-04-27-kebab-final-form-design.md) | **계약 (reconciled baseline)** |
| 설계 기원·근거 (최초 보고서) | [kebab_local_rust_report.md](kebab_local_rust_report.md) | 증거 | | 설계 기원·근거 (최초 보고서) | [kebab_local_rust_report.md](kebab_local_rust_report.md) | 증거 |
| v0.18.0 NLI 검증 도그푸딩 증거 | [docs/dogfood/v0.18.0/](docs/dogfood/v0.18.0/) | 증거 | | v0.18.0 NLI 검증 도그푸딩 증거 | [docs/dogfood/v0.18.0/](docs/dogfood/v0.18.0/) | 증거 |
## 구역 (zones) ## 구역 (zones)
- **living** — 현재 코드베이스의 진실. 기능/표면 변경 시 동기화 필수 (CLAUDE.md §User-facing docs 가 강제). - **living** — 현재 코드베이스의 진실. 기능/표면 변경 시 동기화 필수 (CLAUDE.md §User-facing docs 가 강제).
- **계약 (frozen)** — `docs/superpowers/specs/2026-04-27-…-design.md` 단 하나. "무엇을 의도했나"의 동결 baseline. 편집 금지. 실제 동작이 이와 다르면 **HOTFIXES.md 가 진실**. - **계약 (reconciled baseline)** — `docs/superpowers/specs/2026-04-27-…-design.md` 단 하나. "무엇을 의도했나"의 baseline. 원칙 동결이되 누적 drift/삭제로 현실과 모순되면 **주기적 dated 재조정**(✂/⟳/⚠, 2026-06-27 선례)으로 정합. 그 사이엔 동작이 이와 다르면 **HOTFIXES.md 가 진실**.
- **증거** — 과거 검증/설계 기록 (rust_report, dogfood/v0.18.0). 갱신 안 함. - **증거** — 과거 검증/설계 기록 (rust_report, dogfood/v0.18.0). 갱신 안 함.
- **git history** — 삭제된 historical 문서(plans·handoffs·task specs·feature specs)는 git 에만. `git log --all -- <path>` 로 복구 가능. durable 내용은 이미 living 으로 흡수됨. - **git history** — 삭제된 historical 문서(plans·handoffs·task specs·feature specs)는 git 에만. `git log --all -- <path>` 로 복구 가능. durable 내용은 이미 living 으로 흡수됨.

2
crates/kebab-rag/src/pipeline.rs
View File

@@ -577,7 +577,7 @@ impl RagPipeline {
/// Only the *initial* decompose's parse failure is a refusal. /// Only the *initial* decompose's parse failure is a refusal.
/// ///
/// `prompt_template_version` on the returned `Answer` is /// `prompt_template_version` on the returned `Answer` is
/// [`PROMPT_TEMPLATE_VERSION_MULTI_HOP`] (`rag-multi-hop-v1`) so /// [`PROMPT_TEMPLATE_VERSION_MULTI_HOP`] (`rag-multi-hop-v2`) so
/// eval `compare` can isolate multi-hop runs from single-pass. /// eval `compare` can isolate multi-hop runs from single-pass.
pub fn ask_multi_hop(&self, query: &str, opts: AskOpts) -> Result<Answer> { pub fn ask_multi_hop(&self, query: &str, opts: AskOpts) -> Result<Answer> {
let started = std::time::Instant::now(); let started = std::time::Instant::now();