diff --git a/HANDOFF.md b/HANDOFF.md index 493cb53..b0e58ca 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -79,6 +79,17 @@ P0~P5 직렬. P6~P9 P5 이후 병렬 가능. P9-2/3/4 는 P9-1 의 parallel-safety contract (sub-state slot 패턴) 덕에 병렬 진행 가능 — 같은 `App` 손대지 않음. +### P9 dogfooding 백로그 (fb-26 ~ fb-42) — 4 minor release 분할 + +2026-05-06 도그푸딩 누적 피드백 + "AI agent 가 kebab 을 쓰게 한다" 궁극 목표용 surface 확장. 17 항목 모두 **status: open + brainstorm 선행 필요**. 각 spec 상단 banner 명시. cascade 영향 / 분량 고려해 한 minor 에 묶지 않고 4 분할. 2026-05-06 renumber — **번호 = release 순서**: + +- **0.3.0 — agent foundation**: fb-26 (log), fb-27 (introspection/error wire), fb-28 (readonly/quiet), fb-29 (daemon), fb-30 (MCP), fb-31 (single-file ingest). agent 통합 MVP. +- **0.4.0 — agent surface refinement (additive)**: fb-32 (stale), fb-33 (streaming), fb-34 (budget), fb-35 (verbatim fetch), fb-36 (filters), fb-37 (trace/stats). +- **0.5.0 — RAG quality (cascade 동반)**: fb-38 (score semantics), fb-39 (precision tuning, embedding_version cascade + V00X), fb-40 (fact-grounded, prompt_template_version cascade). +- **0.6.0 또는 P+**: fb-41 (multi-hop, XL), fb-42 (bulk/rerank, Nice). + +각 fb spec frontmatter 의 `target_version` 필드가 source of truth. INDEX.md 의 release subheader 도 동일 grouping. + ## 검증된 운영 동작 (release binary, fastembed enabled) P7-3 머지 직후 25 시나리오 smoke 통과 — markdown + image + PDF 5 자산 워크스페이스에서 doctor / ingest / list / inspect / search (lex/vec/hybrid) / re-ingest / byte-edit re-ingest / corrupt PDF / RAG ask + page citation 모두. 자세한 시나리오 표는 conversation 기록 참조; 워크스페이스에 직접 돌려보는 절차는 [docs/SMOKE.md](docs/SMOKE.md). diff --git a/tasks/INDEX.md b/tasks/INDEX.md index 36dc95d..d5630e6 100644 --- a/tasks/INDEX.md +++ b/tasks/INDEX.md @@ -109,6 +109,32 @@ P0~P5 는 직렬. P6~P9 는 P5 이후 병렬 가능. - [p9-fb-23 incremental ingest (post-도그푸딩)](p9/p9-fb-23-incremental-ingest.md) - [p9-fb-24 status bar + Library header + page scroll (post-도그푸딩)](p9/p9-fb-24-tui-affordances.md) - [p9-fb-25 config workspace.include 제거 + 지원 형식 가시성 (post-도그푸딩)](p9/p9-fb-25-config-include-removal.md) + - **⏳ fb-26 ~ fb-42: 백로그 only — 미구현 + brainstorm 선행 필요.** spec 작성 시 [superpowers:brainstorming](../docs/superpowers/) 부터 시작. status: open. 다른 세션에서 이 그룹 손대기 전 사용자 확인 필요. **번호 = release 순서** — 작은 번호일수록 먼저 작업 (2026-05-06 renumber). + + ### 🎯 0.3.0 — agent foundation (MCP + daemon + introspection) + - [p9-fb-26 ingest 로그 출력 일관성](p9/p9-fb-26-ingest-log-consistency.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-27 introspection + structured error wire](p9/p9-fb-27-introspection-and-error-wire.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-28 agent invocation flags (--readonly / --quiet)](p9/p9-fb-28-agent-invocation-flags.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-29 HTTP daemon (`kebab serve`)](p9/p9-fb-29-http-daemon.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-30 MCP server](p9/p9-fb-30-mcp-server.md) — ⏳ 미구현, brainstorm 필요 (depends_on 27, 29) + - [p9-fb-31 single-file / stdin ingest](p9/p9-fb-31-single-file-stdin-ingest.md) — ⏳ 미구현, brainstorm 필요 + + ### 🎯 0.4.0 — agent surface refinement (additive only) + - [p9-fb-32 stale doc indicator](p9/p9-fb-32-stale-doc-indicator.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-33 streaming ask (ndjson delta)](p9/p9-fb-33-streaming-ask.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-34 output budget controls](p9/p9-fb-34-output-budget-controls.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-35 verbatim fetch](p9/p9-fb-35-verbatim-fetch.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-36 search filter args](p9/p9-fb-36-search-filters.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-37 trace + stats](p9/p9-fb-37-trace-and-stats.md) — ⏳ 미구현, brainstorm 필요 (depends_on 27) + + ### 🎯 0.5.0 — RAG quality (cascade 동반: V00X + reindex) + - [p9-fb-38 score semantics](p9/p9-fb-38-score-semantics.md) — ⏳ 미구현, brainstorm 필요 + - [p9-fb-39 retrieval precision 튜닝](p9/p9-fb-39-retrieval-precision-tuning.md) — ⏳ 미구현, brainstorm 필요 (embedding_version cascade) + - [p9-fb-40 fact-grounded answer](p9/p9-fb-40-fact-grounded-answer.md) — ⏳ 미구현, brainstorm 필요 (prompt_template_version cascade) + + ### 🎯 0.6.0 또는 P+ — reasoning + - [p9-fb-41 multi-hop reasoning](p9/p9-fb-41-multi-hop-reasoning.md) — ⏳ 미구현, brainstorm 필요 (XL, eval 인프라 선행) + - [p9-fb-42 bulk multi-query + re-rank hint](p9/p9-fb-42-bulk-multi-query-rerank.md) — ⏳ 미구현, brainstorm 필요 (Nice) ## Post-merge 핫픽스 diff --git a/tasks/p9/p9-fb-26-ingest-log-consistency.md b/tasks/p9/p9-fb-26-ingest-log-consistency.md new file mode 100644 index 0000000..473ed41 --- /dev/null +++ b/tasks/p9/p9-fb-26-ingest-log-consistency.md @@ -0,0 +1,73 @@ +--- +phase: P9 +component: kebab-cli +task_id: p9-fb-26 +title: "Ingest 로그 출력 일관성 (in-place vs 새 줄 혼재)" +status: open +target_version: 0.3.0 +depends_on: [p9-fb-02] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§7 ingest, §10 UX, §2.4a IngestEvent] +source_feedback: 사용자 도그푸딩 2026-05-05 — `kebab ingest` 진행 로그가 어떨 땐 새 라인으로, 어떨 땐 기존 라인 in-place 갱신으로 나와 일관성 떨어짐. +--- + +# p9-fb-26 — Ingest 로그 출력 일관성 + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. 옵션 A/B/C 중 결정 + behavior contract 확정 후 implementation PR 진행. + +## 증상 + +`kebab ingest` 실행 중 진행 출력이 두 패턴 혼재: + +- **TTY**: indicatif `ProgressBar` 단일 라인 in-place 갱신 (`ScanStarted` / `ScanCompleted` / `AssetStarted` / `AssetFinished`). 마지막 `Completed` / `Aborted` summary 만 별도 새 라인. +- **non-TTY (pipe / less / CI)**: 매 event 마다 `writeln!` 새 라인. +- 같은 세션 안에서도 환경 변경 (예: `kebab ingest 2>&1 | tee log`) 시 출력 형식 바뀜. + +사용자 인지: "어떨 땐 새 라인, 어떨 땐 기존 라인 업데이트". 시각적 노이즈 + 스크롤백에 진행 흔적 일부만 남거나 전체 남는 비대칭. + +## 원인 + +[crates/kebab-cli/src/progress.rs:99-188](../../crates/kebab-cli/src/progress.rs#L99-L188): + +- TTY branch 는 `bar.set_message` / `bar.set_position` 으로 단일 라인 갱신. +- non-TTY branch (`if !tty { writeln!(err, ...) }`) 가 모든 event 마다 추가 라인. +- Completed / Aborted 는 TTY 에서도 `writeln!` 항상 호출 — bar finish 후 summary 한 줄. + +## Goal + +진행 로그의 출력 형식을 환경 무관하게 예측 가능하게 만든다. 사용자는 한 가지 형식을 보고 다른 환경에서도 같은 형식을 기대해야 함. + +## Behavior contract (제안 — brainstorming 단계, 머지 전 사용자 확인) + +옵션 A — **TTY = in-place, non-TTY = append-only, 둘 다 명시적**: +- TTY: 진행 라인은 in-place, summary 도 마지막에 같은 라인 commit (현재 처럼 새 줄 X) 또는 한 줄 띄우고 명시적 final. +- non-TTY: 매 event 한 줄 (현재 동작 유지) — pipe / log redirect 에서 진행 흔적 남는 게 정답. +- summary 라인은 두 모드 동일한 prefix (`ingest: complete (...)` / `ingest: aborted (...)`) 로 통일. + +옵션 B — **항상 append-only**: +- TTY 에서도 spinner 끄고 매 event 새 라인. 단순, 진행 흔적 보존. +- 단점: bar UX 손실 — long ingest 에서 화면 가득. + +옵션 C — **항상 in-place (TTY 만)**: +- non-TTY 면 마지막 summary 한 줄만, 중간 event silent. +- 단점: CI / log redirect 에서 진행 알 수 없음. + +권장: **옵션 A** — 환경별 의미 명확, 두 형식 다 의도된 것임을 README 에 명시. + +## 검증 / 테스트 + +- `kebab ingest` TTY 모드: spinner 한 라인만 차지, 종료 후 summary 한 줄. +- `kebab ingest 2>&1 | cat`: append-only 형식, 매 asset / scan event 한 줄. +- `kebab ingest --json`: 기존 ndjson 동작 유지 (영향 없음). +- snapshot test: non-TTY 스트림 포맷 안정. + +## 관련 항목 + +- p9-fb-01 / p9-fb-02 (progress 인프라). 본 항목은 그 위의 일관성 follow-up. +- 사용자 visible surface — README **명령** 표 / Quick start 의 ingest 출력 예시 갱신 필요. + +## Risks / notes + +- indicatif `ProgressDrawTarget::stderr()` 가 일부 터미널 (TUI multiplexer, 일부 ssh client) 에서 in-place 갱신 fallback 으로 새 라인 그릴 수 있음 — 조사 필요. +- CI 가 TTY-emulating wrapper (예: GitHub Actions 일부) 면 의도 안 한 in-place 모드 진입 가능. 명시적 `KEBAB_PROGRESS=plain` env override 검토. diff --git a/tasks/p9/p9-fb-27-introspection-and-error-wire.md b/tasks/p9/p9-fb-27-introspection-and-error-wire.md new file mode 100644 index 0000000..d390836 --- /dev/null +++ b/tasks/p9/p9-fb-27-introspection-and-error-wire.md @@ -0,0 +1,42 @@ +--- +phase: P9 +component: kebab-cli + kebab-app + wire-schema +task_id: p9-fb-27 +title: "Introspection (`kebab schema`) + structured error wire" +status: open +target_version: 0.3.0 +depends_on: [] +unblocks: [p9-fb-30] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§10 UX, wire-schema 전반] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 kebab 인스턴스의 wire 버전 / 기능 / 모델 / 인덱스 통계 알아야 통합 안전. error 도 stderr text 가 아닌 structured JSON 필요. +--- + +# p9-fb-27 — Introspection + structured error wire + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. capability matrix 정의 / error code enumerate / exit code 매핑 brainstorm 후 확정. + +## 증상 / 동기 + +- agent 가 kebab 의 wire schema 버전 / 기능 플래그 / 모델 정보 / 인덱스 통계 introspect 못 함. +- error 는 stderr text — agent parse 어려움. timeout vs no-results vs config-missing vs not-indexed 구분 불가. + +## Goal (skeleton) + +- `kebab schema --json` — wire schema 버전 list, capability flags (mcp / daemon / streaming / 등), model versions (parser / chunker / embedding / prompt_template / index), index stats (doc count, chunk count, last ingest). +- `kebab stats --json` 으로 분리 가능 — schema 는 정적, stats 는 동적. brainstorm 단계 결정. +- 모든 명령의 error 출력을 structured JSON (stderr ndjson 또는 stdout 의 error.v1 wire). +- exit code: 0 = OK, 1 = generic, 2 = config, 3 = not-indexed, 4 = timeout, 5 = no-results, … + +## 후속 작업 — brainstorm 필요 항목 + +- error.v1 wire schema — fields (`code`, `message`, `details`, `hint`). +- 기존 명령의 error path 전수 변환 — anyhow chain → error.v1. +- schema vs stats 분리 여부. +- fb-30 MCP `initialize` response 와 capability matrix 공유. + +## Risks / notes + +- error wire 변경 = breaking — 기존 stderr text 출력은 유지 (둘 다 출력 또는 `--json` 일 때만 wire). +- exit code 안정성 — README 에 표 명시. +- fb-30 / 29 의 prerequisite — agent 가 server 능력 먼저 introspect. diff --git a/tasks/p9/p9-fb-28-agent-invocation-flags.md b/tasks/p9/p9-fb-28-agent-invocation-flags.md new file mode 100644 index 0000000..93cf1c4 --- /dev/null +++ b/tasks/p9/p9-fb-28-agent-invocation-flags.md @@ -0,0 +1,42 @@ +--- +phase: P9 +component: kebab-cli + kebab-app +task_id: p9-fb-28 +title: "Agent invocation flags (--readonly + --quiet)" +status: open +target_version: 0.3.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§10 UX] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 KB 안전하게 사용 + progress 노이즈 끄기 명시 control 필요. shared / multi-agent host 에서 destructive 명령 차단 필수. +--- + +# p9-fb-28 — Agent invocation flags + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. read-only 의 강제력 (env vs flag vs sub-binary) / quiet 의 범위 (stderr 전체 vs progress 만) brainstorm 후 확정. + +## 증상 / 동기 + +- agent 가 실수로 `kebab nuke` / `kebab reset` 호출 위험 — read-only mode 강제 필요. +- agent invoke 시 progress / spinner stderr 출력이 noise — 명시 quiet flag 필요. +- 현재 TTY auto-detect 로 부분 해결되지만 TTY 가 emulate 된 환경 (예: agent host 의 pty wrapper) 에서 의도 안 한 spinner. + +## Goal (skeleton) + +- `KEBAB_READONLY=1` env 또는 `kebab --readonly ` — destructive 명령 (`reset`, `nuke`, `ingest --overwrite` 등) 거부. +- `kebab --quiet ` — 모든 stderr progress / hint 끔. error 만 stderr. +- agent host 권장 patterns README 에 명시 (예: skill 의 invocation env block). + +## 후속 작업 — brainstorm 필요 항목 + +- read-only 의 enforcement layer — argparse vs runtime check. +- quiet 와 `--json` 관계 — `--json` 이 자동 quiet 인지. +- destructive 명령 enumerate — ingest 가 idempotent 인데 destructive 인지 분류. +- daemon (fb-29) 위에서 read-only token / scope. + +## Risks / notes + +- read-only bypass 우회 (config 직접 수정 등) 는 막을 수 없음 — best-effort. +- 사용자가 자기 invoke 에 readonly 걸지 않게 README 안내. +- fb-30 MCP 의 tool 별 permission 과 통합 (read tool 만 노출 vs read+write). diff --git a/tasks/p9/p9-fb-29-http-daemon.md b/tasks/p9/p9-fb-29-http-daemon.md new file mode 100644 index 0000000..33e8643 --- /dev/null +++ b/tasks/p9/p9-fb-29-http-daemon.md @@ -0,0 +1,45 @@ +--- +phase: P9 +component: kebab-cli + new crate (kebab-server) +task_id: p9-fb-29 +title: "HTTP daemon (`kebab serve`) — subprocess overhead 제거" +status: open +target_version: 0.3.0 +depends_on: [] +unblocks: [p9-fb-30] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§7 RAG, §10 UX] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent loop 가 kebab CLI 를 반복 호출 시 subprocess fork + Lance/SQLite cold start 비용 누적. local HTTP daemon 이 latency 해결. +--- + +# p9-fb-29 — HTTP daemon (`kebab serve`) + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. bind / auth / endpoint scheme / lifecycle (auto-start vs explicit) brainstorm 후 확정. + +## 증상 / 동기 + +- 현재 `kebab search` / `kebab ask` 가 매 호출 process fork — Lance / SQLite / fastembed 모델 로드 cold start. +- agent 가 10 회 search 도는 loop 면 cold start × 10. local-first 단일 사용자라도 latency 누적. +- daemon 으로 띄우면 hot — sub-100ms search 가능. + +## Goal (skeleton) + +- `kebab serve --port --bind 127.0.0.1` — local HTTP API. +- endpoint: `/search`, `/ask`, `/fetch`, `/ingest`, `/stats`, `/schema`. wire schema v1 재사용. +- auth: local bind 면 무인증 (외부 host 면 token). +- streaming `/ask` (Server-Sent Events 또는 chunked). +- lifecycle: 사용자 명시 실행 vs CLI 자동 spawn (XDG runtime path 의 socket). + +## 후속 작업 — brainstorm 필요 항목 + +- web framework: axum / hyper / actix — workspace 통일성 + binary size. +- 단일 인스턴스 보장 (PID file / socket lock). +- daemon ↔ CLI shim — CLI 가 daemon 살아있으면 HTTP 사용, 없으면 fork. +- TUI 와 daemon 공존 — TUI 도 daemon 있으면 HTTP 통해 (현재는 in-process). +- fb-30 (MCP) 와 transport 공유 — MCP-over-HTTP-SSE. + +## Risks / notes + +- 단일 사용자 local 환경 — daemon 없는 단순함 trade-off. +- fb-30 와 강결합 — 함께 brainstorm 하면 architecture 일관. +- security: bind 127.0.0.1 default 강제 — 0.0.0.0 은 명시 opt-in. diff --git a/tasks/p9/p9-fb-30-mcp-server.md b/tasks/p9/p9-fb-30-mcp-server.md new file mode 100644 index 0000000..2015aa5 --- /dev/null +++ b/tasks/p9/p9-fb-30-mcp-server.md @@ -0,0 +1,44 @@ +--- +phase: P9 +component: integrations + new crate (kebab-mcp) +task_id: p9-fb-30 +title: "MCP server — agent host 무관 protocol surface" +status: open +target_version: 0.3.0 +depends_on: [p9-fb-27, p9-fb-29] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§7 RAG, §10 UX, externalAI 통합 절] +source_feedback: 사용자 도그푸딩 2026-05-06 — Claude Code 같은 AI agent 가 kebab CLI 를 사용하는 것이 궁극 목표. 현재 surface 는 Claude Code 전용 skill (subprocess wrapper) 만 — host 무관 표준 통신 없음. +--- + +# p9-fb-30 — MCP server + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. transport 선택 (stdio / socket) / tool surface 범위 / authentication / resources vs tools 매핑 brainstorm 후 확정. + +## 증상 / 동기 + +- 현재 외부 AI 통합은 `integrations/claude-code/kebab/` skill 한 종류 — Claude Code subprocess wrapper. +- Cursor / OpenAI Agents / Copilot CLI 등 다른 host 는 별도 wrapper 작성 필요. +- MCP (Model Context Protocol) 가 표준 — 한 번 server 구현하면 MCP-aware host 모두 지원. + +## Goal (skeleton) + +- `kebab mcp` subcommand 또는 별도 binary `kebab-mcp` — stdio MCP server. +- Tool surface (최소): `search`, `ask`, `fetch`, `ingest_file`, `ingest_stdin`, `stats`, `schema`. +- Resources: 옵션 — chunk / doc 을 MCP resource 로 노출 (host subscribe 가능). +- Prompts: 옵션 — agent 가 재사용 가능한 prompt template (예: "summarize this KB section"). +- skill 과 병행 — skill 은 backward compat, 신규는 MCP 권장. + +## 후속 작업 — brainstorm 필요 항목 + +- transport: stdio default, http (fb-29 daemon) 위에 SSE 옵션. +- tool 이름 / 인자 스키마 — wire schema v1 재사용 가능? +- authentication — local-only 면 무인증, daemon 위면 token. +- 새 crate `kebab-mcp` 위치 / 의존성 boundary (kebab-app facade 만 import). + +## Risks / notes + +- MCP spec 진화 중 — 버전 lock 명시 필요. +- skill 과 surface 중복 — 사용자 혼란 방지 README 안내. +- fb-29 (daemon) 선행 또는 동시 — daemon 모드 위에 MCP HTTP 변형 가능. diff --git a/tasks/p9/p9-fb-31-single-file-stdin-ingest.md b/tasks/p9/p9-fb-31-single-file-stdin-ingest.md new file mode 100644 index 0000000..74026eb --- /dev/null +++ b/tasks/p9/p9-fb-31-single-file-stdin-ingest.md @@ -0,0 +1,42 @@ +--- +phase: P9 +component: kebab-cli + kebab-app +task_id: p9-fb-31 +title: "Single-file / stdin ingest — agent on-demand 저장" +status: open +target_version: 0.3.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§3 ingest, §10 UX] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 읽은 article / fetch 한 page 를 즉시 KB 저장 needed. 현재 ingest 는 workspace 전체 scan 만. +--- + +# p9-fb-31 — Single-file / stdin ingest + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. workspace 외부 file 의 저장 위치 / metadata 입력 방식 / .kebabignore 우회 정책 brainstorm 후 확정. + +## 증상 / 동기 + +- agent 가 web 에서 fetch 한 markdown / pdf 를 KB 에 저장하려 함 — 현재는 workspace 디렉토리에 file 쓰고 `kebab ingest` 전체 재실행. +- agent 메모리상 string contents 도 stdin 으로 ingest 가능해야 — 임시 파일 거치는 비효율 제거. + +## Goal (skeleton) + +- `kebab ingest --file ` — 단일 파일만 ingest, workspace 외부도 가능 (workspace 안 copy 또는 absolute path 등록). +- `kebab ingest --stdin --media md --title "X" [--source-uri "https://..."]` — stdin 에서 contents 읽고 KB 저장. +- 결과는 기존 `ingest_report.v1` 와 동일 shape (단일 asset). +- p9-fb-23 incremental ingest 와 호환 — 단일 파일도 mtime 기반 변경 감지. + +## 후속 작업 — brainstorm 필요 항목 + +- workspace 외부 file 저장 정책 — copy in vs reference (path 만 저장). +- stdin contents 의 doc_id 결정 — content hash + title. +- source URI metadata 표현 — wire schema 추가 필드. +- .kebabignore 우회 — 명시 ingest 면 강제? 아니면 거부? + +## Risks / notes + +- workspace 정의 (§6.2) 와 충돌 가능 — workspace 안 copy 가 깔끔. +- agent 가 무한 ingest 시 KB 비대 — quota / TTL 필요할 수도. +- p9-fb-23, p9-fb-25 (workspace.include 제거) 와 정책 정합성 검토. diff --git a/tasks/p9/p9-fb-32-stale-doc-indicator.md b/tasks/p9/p9-fb-32-stale-doc-indicator.md new file mode 100644 index 0000000..30e5b85 --- /dev/null +++ b/tasks/p9/p9-fb-32-stale-doc-indicator.md @@ -0,0 +1,42 @@ +--- +phase: P9 +component: kebab-app + kebab-tui + kebab-cli +task_id: p9-fb-32 +title: "Stale doc indicator (ingest 시점 대비 X 일 임계 알림)" +status: open +target_version: 0.4.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§3 ingest, §10 UX] +source_feedback: 사용자 도그푸딩 2026-05-06 — Claude Code 가 kebab CLI 사용 후 "최신성 약함" 지적. ingest 시점 snapshot 이라 이후 변경 사실 미반영. local-first 단일 사용자라 web fetch 안 함이 의도지만 사용자 / 외부 도구가 stale 여부 인지 못 함. +--- + +# p9-fb-32 — Stale doc indicator + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. stale threshold 정책 / "stale" 정의 (ingest 시점 vs file mtime) / wire schema 필드 위치 brainstorm 후 확정. + +## 증상 / 동기 + +- 답변에 사용된 chunk 가 N 일 전 ingest snapshot — 사용자 / 외부 도구는 fresh 여부 모름. +- p9-fb-23 (incremental ingest) 가 mtime 변경 doc 만 재처리 — 사용자가 자주 ingest 하면 자연 해결, 단 사용자가 자주 안 돌리는 doc 도 있음. + +## Goal (skeleton — brainstorm 단계에서 확정) + +- 각 search hit / citation 에 `ingested_at` (또는 `age_days`) 필드 노출. +- TUI inspect / search 결과에 stale 표시 (예: 30 일 이상 = 노란색 경고). +- CLI `--json` 도 동일 필드 — 외부 도구가 stale 여부 판단. +- 옵션: stale doc 자동 재 ingest 제안. + +## 후속 작업 — brainstorm 필요 항목 + +- threshold 정책 — 사용자 config 가능 여부 (`stale_threshold_days`). +- "stale" 의 정의 — ingest 시점 vs file mtime 시점 vs 둘 다. +- wire schema search_hit.v1 / answer.v1 의 citation 에 필드 추가 — additive minor. +- TUI 색상 / 표시 방식 — p9-fb-14 color theme 와 통합. + +## Risks / notes + +- p9-fb-23 incremental ingest 와 의존 — `ingested_at` 정확성 위해 incremental 의 timestamp 갱신 동작 확인. +- additive wire 변경이라 외부 통합 영향 적음. +- 사이즈 작음 (S) — 단순 필드 추가 + 표시 로직. diff --git a/tasks/p9/p9-fb-33-streaming-ask.md b/tasks/p9/p9-fb-33-streaming-ask.md new file mode 100644 index 0000000..24c38e1 --- /dev/null +++ b/tasks/p9/p9-fb-33-streaming-ask.md @@ -0,0 +1,46 @@ +--- +phase: P9 +component: kebab-cli + kebab-app + wire-schema +task_id: p9-fb-33 +title: "Streaming ask (ndjson delta) — agent token 즉시 소비" +status: open +target_version: 0.4.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§7 RAG, §10 UX, wire-schema answer.v1] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 token 도착 즉시 다음 행동 결정 가능해야 — final-only JSON 은 latency 손해. +--- + +# p9-fb-33 — Streaming ask (ndjson delta) + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. delta event 형식 / final-only fallback / TUI vs CLI 차이 brainstorm 후 확정. + +## 증상 / 동기 + +- 현재 `kebab ask --json` 추정 — final answer 한 번에 출력. agent 는 LLM token 도착마다 progressive UI / 조기 종료 / 후속 tool 호출 결정 가능해야 빠름. +- TUI 는 이미 streaming 표시 — CLI / agent 가 동일 surface 못 받음. + +## Goal (skeleton) + +- `kebab ask --json --stream` — ndjson delta event. +- event shape (제안): + - `{"kind":"retrieval_done","hits":[...]}` + - `{"kind":"token","delta":"...", "turn_index":0}` + - `{"kind":"citation","ref":"[1]","chunk_id":"..."}` + - `{"kind":"final","answer":"...","citations":[...]}` +- `--stream` 미지정이면 현재 동작 유지 (final-only). +- wire schema `answer_event.v1` 추가. + +## 후속 작업 — brainstorm 필요 항목 + +- event 종류 / 순서 invariant. +- token delta 의 partial markdown — fb-40 fact-grounded / fb-11 markdown render 와 정합성. +- 중간 cancel — agent 가 SIGINT / connection close 하면 LLM 호출 중단. +- daemon (fb-29) HTTP SSE 와 동일 event shape — 이중 구현 방지. + +## Risks / notes + +- wire schema additive minor — 기존 final-only path 보존. +- TUI 의 streaming 코드 재사용 가능 — kebab-rag 의 generate stream API 가 이미 있을 것. +- fb-30 MCP / fb-29 daemon 과 stream surface 통일 필요. diff --git a/tasks/p9/p9-fb-34-output-budget-controls.md b/tasks/p9/p9-fb-34-output-budget-controls.md new file mode 100644 index 0000000..4aa99a8 --- /dev/null +++ b/tasks/p9/p9-fb-34-output-budget-controls.md @@ -0,0 +1,43 @@ +--- +phase: P9 +component: kebab-cli + kebab-app + wire-schema +task_id: p9-fb-34 +title: "Output budget controls (--max-tokens / --snippet-chars / pagination)" +status: open +target_version: 0.4.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search, §10 UX, wire-schema search_hit.v1] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent context window 제한적. 검색 결과 양 / snippet 길이 / 페이지네이션 control 필요. +--- + +# p9-fb-34 — Output budget controls + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. budget 적용 layer (truncate vs k 조정) / cursor 형식 / 기본값 brainstorm 후 확정. + +## 증상 / 동기 + +- agent context window 한정 — 검색 결과 5KB 이하로 받고 싶을 때 control 없음. +- snippet 길이 고정 → narrow context 에서 한 hit 만 받아도 차고 넘침. +- top-5 본 후 추가 5 보고 싶을 때 페이지네이션 없음. + +## Goal (skeleton) + +- `kebab search --max-tokens N` — 결과 직렬화 size 가 N tokens 안에 들도록 truncate / k 자동 축소. +- `kebab search --snippet-chars N` — 각 hit 의 snippet 최대 chars. +- `kebab search --cursor ` — 이전 호출의 cursor 로 다음 페이지. +- response 에 `next_cursor` 필드 (남은 hit 있을 때). + +## 후속 작업 — brainstorm 필요 항목 + +- token 카운트 — tiktoken 류 dependency vs 단순 byte/4 근사. +- truncate 우선순위 — snippet 단축 → k 축소 → metadata 제거. +- cursor 의 안정성 — index 변경 후 cursor 유효성. +- `kebab ask` 도 동일 인자 (`--max-tokens` 결과 답변 길이 제한)? + +## Risks / notes + +- wire schema additive — `next_cursor` 필드 추가 minor. +- agent UX — truncate 발생 시 명시적 hint (`truncated: true`) 필요. +- 기본값 — agent 친화 (작은 budget) vs 사람 친화 (큰 budget) trade-off. diff --git a/tasks/p9/p9-fb-35-verbatim-fetch.md b/tasks/p9/p9-fb-35-verbatim-fetch.md new file mode 100644 index 0000000..c8267da --- /dev/null +++ b/tasks/p9/p9-fb-35-verbatim-fetch.md @@ -0,0 +1,43 @@ +--- +phase: P9 +component: kebab-cli + kebab-app + wire-schema +task_id: p9-fb-35 +title: "Verbatim fetch (`kebab fetch `) — citation deep-link" +status: open +target_version: 0.4.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search, §5 storage, §10 UX] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 search hit / citation 보고 더 깊이 파볼 때 raw chunk text + 주변 context 필요. +--- + +# p9-fb-35 — Verbatim fetch + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. fetch unit (chunk vs doc vs span) / 주변 context (앞뒤 chunk N 개) / 옵션 정책 brainstorm 후 확정. + +## 증상 / 동기 + +- search 결과의 snippet 은 highlight 중심 — agent 가 "이 chunk 의 전체 raw text" 또는 "이 chunk 앞뒤 context" 원함. +- 현재 inspect 는 TUI 전용 — CLI / `--json` 으로 chunk 가져오는 명시 surface 없음. +- citation 의 doc_id 만 받고 doc 전체 다시 ingest / read 하는 비효율. + +## Goal (skeleton) + +- `kebab fetch chunk [--context N]` — chunk verbatim + 앞뒤 N 개 chunk. +- `kebab fetch doc ` — doc 전체 raw text. +- `kebab fetch span ` — 특정 라인 범위. +- response wire schema `fetch_result.v1` 추가. + +## 후속 작업 — brainstorm 필요 항목 + +- chunk_id / doc_id 노출 — 현재 search_hit.v1 에 있는지 확인 + 안정성. +- context window — N 개 chunk vs N tokens. +- doc 전체 fetch 의 size 제한 (fb-34 budget 과 통합). +- pdf / image 의 fetch — 텍스트 추출본 vs 원본 path. + +## Risks / notes + +- wire schema 신규 — `fetch_result.v1` JSON Schema 추가. +- 큰 doc fetch 시 budget control 필수 — fb-34 와 통합. +- chunk_id 안정성 — re-ingest 후 chunk_id 변경되면 agent 의 citation stale. diff --git a/tasks/p9/p9-fb-36-search-filters.md b/tasks/p9/p9-fb-36-search-filters.md new file mode 100644 index 0000000..a0007fe --- /dev/null +++ b/tasks/p9/p9-fb-36-search-filters.md @@ -0,0 +1,43 @@ +--- +phase: P9 +component: kebab-cli + kebab-search + wire-schema +task_id: p9-fb-36 +title: "Search filter args (--media / --ingested-after / --doc-id / --tag)" +status: open +target_version: 0.4.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 검색 범위 좁힐 수단 필요. 현재 search 는 query string 만 받음. +--- + +# p9-fb-36 — Search filter args + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. filter 종류 / SQLite 쿼리 통합 / Lance vector 필터 적용 layer brainstorm 후 확정. + +## 증상 / 동기 + +- agent 가 "최근 1 주 내 doc 중에서만" / "pdf 만" / "tag=research 만" 검색 원함. +- 현재 query 만 받고 후처리 filter 도 없음. + +## Goal (skeleton) + +- `kebab search Q --media md,pdf` — media type 필터. +- `kebab search Q --ingested-after 2026-04-01` — ingest 시점 필터 (fb-32 stale 와 연계). +- `kebab search Q --doc-id ` — 특정 doc 의 chunk 만. +- `kebab search Q --tag ` — tag 시스템 도입 시 (선행 brainstorm). +- `--exclude-doc-id`, `--exclude-tag` 도 검토. + +## 후속 작업 — brainstorm 필요 항목 + +- tag 시스템 도입 여부 — 새 SQLite 테이블 / migration. +- filter 적용 layer — SQLite WHERE 절 + Lance vector pre-filter. +- AND vs OR 의미 — 다중 filter 조합 default. +- 기존 wire `SearchRequest` 에 추가 필드 (additive minor). + +## Risks / notes + +- Lance vector pre-filter 가 효율적인지 (post-filter 면 k 부족 가능). +- tag 시스템은 큰 추가 — 분리 spec 으로 갈 수도. +- fb-32 (stale) 의 `ingested_at` 필드와 통합 — 같은 batch. diff --git a/tasks/p9/p9-fb-37-trace-and-stats.md b/tasks/p9/p9-fb-37-trace-and-stats.md new file mode 100644 index 0000000..e881ce9 --- /dev/null +++ b/tasks/p9/p9-fb-37-trace-and-stats.md @@ -0,0 +1,46 @@ +--- +phase: P9 +component: kebab-cli + kebab-search + kebab-rag +task_id: p9-fb-37 +title: "Trace (--trace) + stats — pipeline 가시성" +status: open +target_version: 0.4.0 +depends_on: [p9-fb-27] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search, §7 RAG, §10 UX] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent / 사용자가 "왜 이 결과가 나왔는지" debug 필요. retrieval pipeline 의 각 stage 결과 + KB 건강 점검 surface 부재. +--- + +# p9-fb-37 — Trace + stats + +> ⏳ **백로그 only — 미구현 (Nice-to-have).** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. trace 의 verbosity level / wire shape / stats 의 별도 명령 vs schema 통합 brainstorm 후 확정. + +## 증상 / 동기 + +- search 결과 의문 — lexical / vector / RRF / rerank 각 stage 가 무엇 반환했는지 모름. +- KB 건강 — doc count / chunk count / last ingest / index size / model versions — 단일 surface 없음. +- agent 가 stale 판단 / 사용자가 디버깅 시 둘 다 필요. + +## Goal (skeleton) + +- `kebab search Q --trace` 또는 `--explain` — 응답에 `trace` 필드: + - `lexical_hits: [{doc_id, score, …}]` + - `vector_hits: [...]` + - `rrf_combined: [...]` + - `reranked: [...]` (reranker 도입 시) + - `timing: {lexical_ms, vector_ms, fusion_ms, total_ms}` +- `kebab stats --json` — KB 통계 (fb-27 의 schema 와 별도 명령 또는 통합). +- TUI inspect 에 trace view — 1 hit 클릭 시 stage breakdown. + +## 후속 작업 — brainstorm 필요 항목 + +- trace 의 verbosity — 모든 stage default vs flag opt-in (응답 size 우려). +- stats 명령의 위치 — `kebab stats` 또는 `kebab schema --include-stats`. +- timing 정확도 — async stage 는 wall-clock 부정확. + +## Risks / notes + +- trace 응답 size 큼 — agent budget (fb-34) 와 충돌 가능, 기본 OFF 권장. +- fb-27 introspection 의 stats 와 중복 — brainstorm 단계 통합 결정. +- 우선순위 낮음 — 핵심 기능 (fb-26 ~ 36) 후순위. diff --git a/tasks/p9/p9-fb-38-score-semantics.md b/tasks/p9/p9-fb-38-score-semantics.md new file mode 100644 index 0000000..84bcad3 --- /dev/null +++ b/tasks/p9/p9-fb-38-score-semantics.md @@ -0,0 +1,40 @@ +--- +phase: P9 +component: kebab-search + kebab-app + wire-schema +task_id: p9-fb-38 +title: "Score semantics 노출 + 문서화 (RRF score 천장 / 채널별 score 분리)" +status: open +target_version: 0.5.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search, §10 UX, wire-schema search_hit.v1] +source_feedback: 사용자 도그푸딩 2026-05-06 — Claude Code 가 kebab CLI 사용 후 "top score ~0.5 천장" 지적. RRF 의 rank-only fusion 특성상 absolute relevance 가 아닌데 외부 도구가 score 를 confidence 로 오해. +--- + +# p9-fb-38 — Score semantics 노출 + 문서화 + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. score field naming / wire schema 변경 범위 / 채널별 score 노출 정책 brainstorm 후 확정. + +## 증상 / 동기 + +- hybrid 검색의 RRF score 가 일정 ceiling 에 머무름. RRF 수식 (`2/(k+rank)`, post-merge hotfix) 상 max = `2/(k+1)`. +- 외부 도구 (Claude Code skill, MCP) 가 `score` 를 0~1 confidence 로 해석 → "0.5 면 50% 확신" 오용. +- 단일 channel score (raw BM25 / cosine sim) 가 wire 에 노출 안 됨 — 디버깅도 어려움. + +## Goal (skeleton — brainstorm 단계에서 확정) + +- score 의 의미를 wire 와 README 에 명시. +- 채널별 raw score (lexical BM25, vector cosine) 를 search_hit 에 옵션 필드로 노출. +- RRF score 와 channel score 의 관계 / scale 문서화. + +## 후속 작업 — brainstorm 필요 항목 + +- score field 를 그대로 둘지 (legacy), `rrf_score` / `lexical_score` / `vector_score` 분리할지. +- wire schema 변경이 additive (minor) 인지 breaking (major) 인지 결정. +- README / docs/wire-schema 갱신 범위. + +## Risks / notes + +- wire schema breaking 시 외부 통합 (claude-code skill 등) 영향 — 버전 cascade 필요. +- spec PR 우선 — design §4 search score scale 정의 추가. diff --git a/tasks/p9/p9-fb-39-retrieval-precision-tuning.md b/tasks/p9/p9-fb-39-retrieval-precision-tuning.md new file mode 100644 index 0000000..724a6fb --- /dev/null +++ b/tasks/p9/p9-fb-39-retrieval-precision-tuning.md @@ -0,0 +1,43 @@ +--- +phase: P9 +component: kebab-search + kebab-rag + kebab-chunk +task_id: p9-fb-39 +title: "Retrieval precision 튜닝 (rank 5+ 노이즈 완화)" +status: open +target_version: 0.5.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§3 chunking, §4 search, §7 RAG] +source_feedback: 사용자 도그푸딩 2026-05-06 — Claude Code 가 kebab CLI 사용 후 "rank 5+ 부터 노이즈 섞임" 지적. precision-at-k 가 k=5 이후 떨어짐. +--- + +# p9-fb-39 — Retrieval precision 튜닝 + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. 어느 lever (chunk policy / RRF k / score gate / cross-encoder / embedding 업그레이드) 부터 손볼지, eval golden set 선행 여부 brainstorm 후 결정. + +## 증상 / 동기 + +- top-1~4 chunk 는 관련 있으나 5번째부터 무관 chunk 섞임. recall OK, precision-at-k 저하. +- LLM 이 noise chunk 를 context 에 포함하면 답변 품질 저하 / hallucinate 위험. + +## Goal (skeleton — brainstorm 단계에서 확정) + +- top-k 결과의 precision 향상. 후보: + 1. chunk policy 재검토 (size / overlap / boundary). + 2. RRF k 파라미터 (현재 default 60) 재튜닝 또는 score gate threshold default ON. + 3. cross-encoder reranker PoC — top-N retrieve → rerank → top-k. + 4. embedding model 업그레이드 (fastembed default → 더 큰 / 한글 강한 모델). +- 평가 지표: P@5, P@10, MRR, NDCG. P5 eval runner 활용. + +## 후속 작업 — brainstorm 필요 항목 + +- 어느 lever 부터 손볼지 — 비용 / 효과 trade-off. +- cross-encoder 도입 시 local-only 유지 가능한지 (fastembed cross-encoder 지원?). +- embedding 변경이면 `embedding_version` cascade — 전체 재처리 필요. + +## Risks / notes + +- embedding_version bump = 전체 vector index 재구축. p9-fb-23 incremental ingest 와 충돌 가능. +- cross-encoder 는 latency 증가 — 단일 사용자 local 환경에서 받아들일 수 있는지 확인. +- eval golden set 부족하면 튜닝 불가 — golden set 확장 선행 필요할 수 있음. diff --git a/tasks/p9/p9-fb-40-fact-grounded-answer.md b/tasks/p9/p9-fb-40-fact-grounded-answer.md new file mode 100644 index 0000000..ab64333 --- /dev/null +++ b/tasks/p9/p9-fb-40-fact-grounded-answer.md @@ -0,0 +1,43 @@ +--- +phase: P9 +component: kebab-rag + kebab-llm +task_id: p9-fb-40 +title: "Fact-grounded answer 강화 (citation 강제 + 근거 없음 fallback)" +status: open +target_version: 0.5.0 +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§7 RAG, prompt template] +source_feedback: 사용자 도그푸딩 2026-05-06 — Claude Code 가 kebab CLI 사용 후 "fact extraction 은 RAG 한계" 지적. fact 단위 질문에서 LLM 이 retrieved chunk 외 internal knowledge 로 답하거나 hallucinate. +--- + +# p9-fb-40 — Fact-grounded answer 강화 + +> ⏳ **백로그 only — 미구현.** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. citation 강제 형식 / 검증 layer / "모름" fallback trigger / prompt_template_version cascade 영향 brainstorm 후 확정. + +## 증상 / 동기 + +- "X 의 정확한 값 / 날짜 / 숫자" 류 질문에서 LLM 이 retrieved chunk 의 fact 와 internal knowledge 충돌 시 internal 우세. +- 근거 부족한 질문에도 LLM 이 그럴듯한 답 생성 — hallucinate. +- RAG 본질적 한계지만 prompt / 검증 layer 로 완화 가능. + +## Goal (skeleton — brainstorm 단계에서 확정) + +- 답변의 모든 fact 가 retrieved chunk 안 span 으로 매핑되도록 강제. +- 근거 부족 시 "모름" 답변 fallback. +- citation 미포함 답변 거부 또는 경고. + +## 후속 작업 — brainstorm 필요 항목 + +- prompt template 수정 — citation 강제 형식 (예: `[doc_id#L]` inline). +- post-generation 검증 — 답변의 fact span 이 retrieved chunk 에 있는지 substring / fuzzy 매치. +- "모름" fallback 의 trigger 조건 (top score gate, chunk count 등). +- prompt_template_version cascade — bump 필요. + +## Risks / notes + +- 너무 strict 하면 정상 답변도 차단 — 경고만 / 거부의 trade-off. +- post-generation 검증은 latency 증가. +- prompt_template_version bump → eval re-run 필요. +- p9-fb-15 (RAG multi-turn) 와 prompt 변경 영역 겹침 — 같은 batch 가능. diff --git a/tasks/p9/p9-fb-41-multi-hop-reasoning.md b/tasks/p9/p9-fb-41-multi-hop-reasoning.md new file mode 100644 index 0000000..08857cd --- /dev/null +++ b/tasks/p9/p9-fb-41-multi-hop-reasoning.md @@ -0,0 +1,41 @@ +--- +phase: P9 +component: kebab-rag + kebab-search +task_id: p9-fb-41 +title: "Multi-hop reasoning / query decomposition (P+, 큰 작업)" +status: open +target_version: 0.6.0+ +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§7 RAG] +source_feedback: 사용자 도그푸딩 2026-05-06 — Claude Code 가 kebab CLI 사용 후 "추론 약함" 지적. RAG 가 chunk 독립 처리, multi-hop inference (A→B→C) 못 봄. +--- + +# p9-fb-41 — Multi-hop reasoning / query decomposition + +> ⏳ **백로그 only — 미구현 (P+, 큰 작업).** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. MVP 범위 / iteration 분할 / decomposition vs graph-retrieval 접근 선택 brainstorm 후 결정. 다른 fb 항목보다 우선순위 낮음. + +## 증상 / 동기 + +- 다단계 추론 질문 ("X 와 Y 의 공통 prerequisite 인 Z 는?") 에서 single-pass retrieval 로는 chunk 간 관계 못 읽음. +- 사용자 질문을 sub-question 으로 분해 + 각각 retrieve + 결과 합성하면 답 가능. + +## Goal (skeleton — brainstorm 단계에서 확정) + +- query decomposition pipeline — LLM 이 사용자 질문을 sub-question N 개로 분해. +- 각 sub-question 으로 separate retrieval → 결과 합성 → 최종 답변. +- 또는 graph-based retrieval — chunk 간 link (citation, entity, doc 관계) 활용. + +## 후속 작업 — brainstorm 필요 항목 + +- decomposition 의 trigger — 모든 질문에 적용 vs 사용자 명시 / heuristic 탐지. +- LLM 호출 횟수 증가 → latency / cost. 단일 사용자 local 에서 acceptable 한지. +- graph 구조면 SQLite 새 테이블 + parser 가 link 추출 — schema migration 필요. +- evaluation — multi-hop golden set 추가 필요. + +## Risks / notes + +- 큰 작업 (XL). MVP 범위 / iteration 분할 brainstorm 단계 결정. +- p9-fb-15 (multi-turn) 의 follow-up turn 으로 자연 분해되는 부분 있음 — overlap 검토. +- 효과 측정 어려움 — eval golden set 없으면 체감 평가만 가능. diff --git a/tasks/p9/p9-fb-42-bulk-multi-query-rerank.md b/tasks/p9/p9-fb-42-bulk-multi-query-rerank.md new file mode 100644 index 0000000..efa82c0 --- /dev/null +++ b/tasks/p9/p9-fb-42-bulk-multi-query-rerank.md @@ -0,0 +1,41 @@ +--- +phase: P9 +component: kebab-cli + kebab-search +task_id: p9-fb-42 +title: "Bulk multi-query + re-rank hint — agent loop 효율" +status: open +target_version: 0.6.0+ +depends_on: [] +unblocks: [] +contract_source: ../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md +contract_sections: [§4 search] +source_feedback: 사용자 도그푸딩 2026-05-06 — agent 가 N 개 query 동시 검색 / 결과 set 을 다른 관점으로 재정렬 원함. 현재는 N 회 subprocess 호출 + 단일 정렬 기준. +--- + +# p9-fb-42 — Bulk multi-query + re-rank hint + +> ⏳ **백로그 only — 미구현 (Nice-to-have).** 본 spec 은 도그푸딩 피드백 skeleton. 구현 착수 전 [superpowers:brainstorming](../../docs/superpowers/) 으로 설계 단계 선행 필요. multi-query input 형식 / 결과 합성 정책 / re-rank hint 의 LLM 호출 비용 brainstorm 후 확정. + +## 증상 / 동기 + +- agent 가 query decomposition (fb-41) 후 N 개 sub-query 검색 — N 회 subprocess fork. +- 검색 결과 set 보고 "이 중 X 관점으로 다시 정렬" 요청 — 현재는 client 측에서 재호출. + +## Goal (skeleton) + +- `kebab search --queries '[{"q":"a","k":5},{"q":"b","k":5}]'` — bulk JSON input. response 는 query 별 결과 array. +- `kebab search Q --rerank-hint "focus on X"` — top-N retrieve 후 LLM 재정렬 (cross-encoder 가능 시 selection). + +## 후속 작업 — brainstorm 필요 항목 + +- bulk input 형식 — JSON array / ndjson stdin. +- 결과 stream vs final — 큰 multi-query 면 stream 유리. +- re-rank hint 의 LLM 모델 — kebab-llm 의 default 사용. +- fb-39 (precision tuning) 의 cross-encoder 와 re-rank hint 통합 가능. +- fb-29 daemon 위에서 더 의미 — subprocess overhead 이미 daemon 으로 해소되면 우선순위 낮음. + +## Risks / notes + +- Nice-to-have — fb-30 / 29 / 31 / 34 / 35 보다 우선순위 낮음. +- re-rank hint 는 LLM 호출 추가 — latency / cost. +- fb-39, fb-41 와 영역 겹침.