# v0.3.x Session Closure — 2026-05-17

> Single-day sprint that closed Cognitive Layer Phase 0+1+2 (core PRs)
> and Cycle 12 Operational UX (PR-O1 → PR-O6). 16 PRs merged on top of
> the v0.3.0 release. Next session picks up from this document.

---

## 1. main HEAD

```
4142018  feat(reasoning): tool router — Phase 2 PR-8 (#295)
87172c3  feat(graph): node attribute editor — PUT /admin/graph/node (PR-O6) (#294)
a6b2e61  refactor(reasoning): split engine.py — memory + synth modules (rule #5) (#293)
09acf86  feat(policy): external isolation via query.internal_rag (PR-O5) (#292)
7cdb7ec  fix(reasoning): N-3 long_ctx isolation on new sessions (PR-O4) (#291)
9077897  feat(reasoning): verification engine — Phase 2 PR-6 (#290)
3dc39f5  feat(reasoning): reflection loop — Phase 2 PR-5 (#289)
a5abf7f  refactor(reasoning): split pipeline.py into loops + synth modules (rule #5) (#288)
6c8e9d2  feat(retrieval): LLM query rewriter — Phase 1 PR-2 (#287)
28453c7  feat(retrieval): cross-encoder reranker — Phase 1 PR-1 (#286)
9a587e4  chore(reasoning): replay_trace.py — reconstruct reasoning from audit_log (L2) (#285)
e05f4f1  feat(reasoning): trace_synth_call wiring on 12 LLM call sites (L1) (#284)
412ef21  feat(reasoning): claude_code_cli backend + trace_schema MVP (L0) (#283)
ea4b4b1  docs(arch): §5.7.2 reasoning backends + trace_schema 단락 추가 (Pre-L0) (#282)
7239d93  docs(release): v0.3.0 changelog + release notes (#281)
```

15 commits + v0.3.0 release tag.

---

## 2. v0.3.0 release (#281)

- CHANGELOG.md 의 stale `[Unreleased] — v0.2 Foundation Hardening`
  헤더를 `[0.2.0]` 으로 정정 + `[0.3.0]` Platform Skeleton 섹션 신설
- `docs/release_notes_v0.3.0.md` 신규 — v0.2.0 컨벤션 (영문 본문 +
  한국어 요약 + 11 테마 분류 + Breaking + Upgrade + What's next)
- 190 commits 정리 (v0.2.0 → v0.3.0)
- GitHub Release: <https://github.com/Hashevolution/James-RAG-Evol/releases/tag/v0.3.0>
- `--prerelease` 없음 (v0.2.0 패턴 그대로 정식 release)

---

## 3. Cognitive Layer — Phase 0+1+2 핵심 완료

### Phase 0 — Infrastructure (4 PR)

| # | PR | 산출물 |
|---|---|---|
| Pre-L0 | #282 | `docs/ARCHITECTURE.md §5.7.2` — backends + trace_schema 단락 (`architecture` 라벨) |
| L0 | #283 | `core/reasoning/trace_schema.py` + `core/reasoning/backends/` (Backend Protocol + registry + ollama_local / claude_code_cli). wiring 0 |
| L1 | #284 | 12 `call_gemma` 호출 site 에 `trace_synth_call` wrap. audit row 발생 시작 |
| L2 | #285 | `scripts/replay_trace.py` — trace_id 로 reasoning sequence 재구성 |

### Phase 1 — Retrieval Intelligence (3 PR)

| # | PR | 산출물 | 디폴트 |
|---|---|---|---|
| PR-1 | #286 | cross-encoder reranker (`core/retrieval/rerank.py`) — `cross-encoder/ms-marco-MiniLM-L-6-v2` ~80MB | **ON** (`JAMES_DISABLE_RERANK=1` 로 끄기) |
| PR-2 | #287 | LLM query rewriter (`core/retrieval/query_rewriter.py`) | **OFF** (`JAMES_ENABLE_QUERY_REWRITE=1` 로 켜기) |
| split | #288 | `pipeline.py` 33.7 KB → 15 KB (rule #5). `pipeline_loops.py` / `pipeline_synth.py` 추출 | — |

PR-3 Hybrid / PR-4 Adaptive — 원래 plan 의 "선택" 표시. **현재 orchestrator 가 이미 BM25+vector hybrid** + adaptive 는 spot-check 후 결정. 본 세션 out of scope.

### Phase 2 — Reasoning Depth (3 PR)

| # | PR | 산출물 | 디폴트 |
|---|---|---|---|
| PR-5 | #289 | Reflection loop (`core/reasoning/reflect.py`) — draft → critique → revised | **OFF** (`JAMES_ENABLE_REFLECT=1`) |
| PR-6 | #290 | Verification engine (`core/reasoning/verify.py`) — security_validator (휴리스틱) + fact_checker (LLM) | **OFF** (`JAMES_ENABLE_VERIFY=1` + 별도 `JAMES_ENABLE_FACT_CHECK=1`) |
| PR-8 | #295 | Tool Router (`core/reasoning/tool_router.py`) — read/write 분리, write 는 CR-E 자동 wrap. wiring 0 | — |

PR-7 Planner — 본 세션 out of scope. Tool Router 의 자연 wiring 후보.

### Phase 2 의 "core differentiator" 작동 증거

§5.7.2 trace-replay invariant — 한 `trace_id` 의 전체 cognitive 시퀀스
재구성 가능. 모든 환경변수 ON 시 8 단계:

```
[1] reasoning.retrieve.query_rewrite   ollama_local
[2] reasoning.rerank.cross_encoder     cross_encoder
[3] reasoning.synth.rag                ollama_local
[4] reasoning.reflect.critique         ollama_local
[5] reasoning.reflect.revised          ollama_local
[6] reasoning.verify.security          —
[7] reasoning.verify.fact_check        ollama_local
[8] reasoning.verify.final             —
```

(`reasoning.tool.<name>` 도 미래 wiring 시 [N] 위치에 삽입.)

`scripts/replay_trace.py <trace_id>` 로 inspect.

---

## 4. Cycle 12 Operational UX — 핵심 6 PR 완료

| # | PR | 항목 | 산출물 |
|---|---|---|---|
| PR-O1 | #277 | ⑥-a 노드 클릭 403 | `frontend/static/graph.js` Authorization Bearer 추가 (5 line) |
| PR-O2 | #279 | ② 제안 칩 NL 패턴 | 3 자연어 정규식 + threshold ≥1 |
| PR-O3 | #280 | ③ 저장 chip spinner | mint accent ring + ✓/✗ |
| PR-O4 | #291 | ① N-3 long_ctx 격리 | engine.py 의 long_ctx fetch 를 hist_ctx 게이트 (새 세션 첫 turn → long_ctx 제외) |
| PR-O5 | #292 | ④ external 격리 | `query.internal_rag` feature 신설 (external 차단) + engine 게이트 |
| PR-O6 | #294 | ⑥-b 노드 편집 backend | `core/graph_node_editor.py` + `PUT /admin/graph/node` |
| PR-O6b | — | ⑥-b/d frontend + i18n | **pending** — UI 토글 + 한글화 |
| PR-O7 | — | ⑥-c 드래그 + 클릭 연결 | **deferred** — 별 사이클 |

### 사용자 차단 회복 4건

- **N-3** (새 세션이 prior session 분석 끌어옴) — PR-O4 가 진짜 fix.
  PR #257 의 부분 fix 위에서 long_ctx 자체를 새 세션에서 제외.
- **노드 클릭 403** — PR-O1 micro-fix.
- **제안 칩 안 잡힘** — PR-O2 NL 패턴 추가.
- **저장 진행 미피드백** — PR-O3 spinner.

---

## 5. CLAUDE.md rule #5 module-size cleanup (2 PR)

| # | PR | 대상 | Before → After |
|---|---|---|---|
| split | #288 | `pipeline.py` | 33.7 KB → 15.0 KB (+ `pipeline_loops.py` 8.8 KB + `pipeline_synth.py` 15.2 KB) |
| split | #293 | `engine.py` | 23.7 KB → 14.0 KB (+ `engine_memory.py` 8.0 KB + `engine_synth.py` 6.2 KB) |

PR-O6 의 graph_editor 도 새 함수 추가로 18.4 → 26.5 KB 가 되자 즉시
`graph_node_editor.py` 분리 (PR #294 안에서 self-contained).

### 잔여 rule #5 debt

- `core/reasoning/modes.py` — 30 KB. pre-existing. 본 세션 untouched.
  PR-O6 에서 가능했지만 별 concern (mode dispatcher vs tool router).
  **별 chore PR 권장**: per-mode handler 5개를 `modes/chat.py` /
  `modes/wiki_edit.py` / `modes/self_evolve.py` / `modes/coding.py` /
  `modes/meta.py` 로 분리. 자연 경계 (각 핸들러는 독립 함수).

---

## 6. 환경변수 정리 — 오늘 세션 새 항목

```bash
# Phase 1 (디폴트 ON, 끌 때만 set):
JAMES_DISABLE_RERANK=1
JAMES_RERANKER_MODEL=BAAI/bge-reranker-base   # 멀티링구얼 swap

# Phase 1 PR-2 / Phase 2 (디폴트 OFF, 켤 때만 set):
JAMES_ENABLE_QUERY_REWRITE=1     # +5-10s/query, retrieval 풍부화
JAMES_ENABLE_REFLECT=1           # +5-15s/query, critique+revise
JAMES_ENABLE_VERIFY=1            # ~5ms/query, security scan
JAMES_ENABLE_FACT_CHECK=1        # 추가 +5-15s/query, claims 검증 (VERIFY=1 필요)

# Phase 0 (claude_code_cli 백엔드 opt-in):
JAMES_ENABLE_CLAUDE_BACKEND=1    # registry 에 claude_code_cli 등록
JAMES_CLAUDE_CLI_PATH=/path/to/claude   # 비명시면 PATH 검색

# PR-O5 — 운영자가 external 에게 internal RAG 풀고 싶을 때:
# admin matrix UI 에서 query.internal_rag × external 체크 (또는 SQL override)
```

---

## 7. 사용자 직접 액션 (라이브 검증 대기)

오늘 머지된 16 PR 의 누적 효과 spot-check. 자세한 가이드는 채팅 기록
참조 ("라이브 검증 어떻게 하지?" 응답).

### 가장 우선 (5분, 환경변수 불필요)

1. **PR-O4 N-3 검증** — session A 에서 query 1건 → session B 로 새
   chat "안녕" → 인사 정상 + prior 내용 없음 확인
2. **PR-O1 노드 클릭** — admin graph 페이지에서 노드 클릭 → 요약 패널
   정상 (403 사라짐)

### 옵트인 spot-check (각 10-15분)

3. **Phase 1 PR-1 Reranker** (디폴트 ON) — 첫 query 에서 모델 다운로드
   ~10-30s, 이후 cache. `replay_trace.py --recent` 로 trace_id 찾고
   `replay_trace.py <id>` 로 `reasoning.rerank.cross_encoder` 행 확인
4. **Phase 1 PR-2 Query rewriter** — `JAMES_ENABLE_QUERY_REWRITE=1`
   + 모호한 query → trace 에 `reasoning.retrieve.query_rewrite` 행
5. **Phase 2 PR-5 Reflection** — `JAMES_ENABLE_REFLECT=1` + 비교 query
   → trace 에 `reasoning.reflect.critique` / `reasoning.reflect.revised`
6. **Phase 2 PR-6 Verification** — `JAMES_ENABLE_VERIFY=1` + injection
   echo query → `recommendation=block`
7. **PR-O5 external 격리** — external role 로 query → handle_chat
   fallback (내부 RAG 우회) 확인
8. **PR-O6 node edit** — `JAMES_GRAPH_EDIT=1` + `PUT /admin/graph/node`
   API call → wiki 파일 frontmatter 갱신

### STEP 7 bench (정량 회귀 정리)

```powershell
python scripts/bench.py --suite=step7 --check
```

기본 baseline 으로 회귀 0 기대 (모든 옵트인 OFF). 옵트인 켜고 측정해서
precision/recall/latency delta 기록 → 다음 세션의 default-ON 결정 근거.

---

## 8. 다음 세션 진입 큐 (권장 순서)

### 🔴 우선 — 라이브 spot-check 결과 보고

위 8 항목 중 사용자가 검증 가능한 만큼. 결과 (정상 / 회귀 / surprising
behavior) 가 다음 작업 방향 결정.

### 🟠 코드 작업 후보 (병렬)

| 우선 | PR | 산출물 | 규모 |
|---|---|---|---|
| 🟠 | **Phase 2 PR-7 Planner** — task decomposition + Tool Router wiring (PR-8 wiring) | Phase 2 완전 마감 | 중-대 |
| 🟠 | **PR-O6b** — frontend "Edit node" 토글 + i18n 한글화 | PR-O6 (#294) backend 의 즉각 가시 가치 | 중 |
| 🟡 | **chore: modes.py split** — 30 KB rule #5 debt 해소 | 5 핸들러 분리 | 중 |
| 🟡 | **Phase 3 PR-9 Episodic memory** — §5.7.6 session/workspace scope 코드 | 새 phase 시작 | 중-대 |
| 🟢 | **Default ON 검토** — Phase 2 PR-5/-6 의 디폴트 ON 전환 (spot-check 후) | 환경변수 디폴트 변경 | 소 |

### 🔵 슬립 (트리거 발생 시 재개)

- Plugin API (사이클 7) — 외부 기여자 트리거 부재
- CLA Track B (사이클 4) — 외부 PR 도착 시
- PR-O7 노드 드래그 + 클릭 연결 — 별 사이클 후보 (UX 규모 큼)
- Phase D surgical triple cascade — Knowledge Cascade 정제 follow-up
- Audit Phase 4b-2 JSONL writer 제거 — 2-4주 mirror reliability 모니터링 후

---

## 9. 핵심 invariant — 잊지 말 것

| Invariant | 위치 | 위배 시 회귀 |
|---|---|---|
| `compute_confidence_from_sources([{weight:0.7}])` == `0.7` | `core/relations_schema.py` | Phase A/B 마이그레이션 깨짐 |
| 모든 relation 의 `confidence` 필드 보존 | `core/cascade.py`, `core/graph_editor.py` | confidence drift |
| `role: "legacy"` source 는 file-delete cascade 에서 제외 | `core/cascade.py` | legacy entity 사라짐 |
| `audit_log.endpoint` 가 `reason:<stage>` prefix | `core/reasoning/trace_schema.py` | replay tool 깨짐 |
| Tool Router write → 항상 CR-E 통과 | `core/reasoning/tool_router.py` | rule #3 위반 |
| `query.internal_rag` 거부 → `handle_chat` fallback | `core/reasoning/engine.py` | external 격리 깨짐 |
| 새 세션 첫 turn (hist_ctx == "") → long_ctx 제외 | `core/reasoning/engine_memory.py` | N-3 재발 |
| `entity_id` 는 절대 변경 안 됨 | `core/graph_node_editor.py` | 그래프 무결성 깨짐 |
| `chat_continuity directive` 는 `hist_ctx` 에만 게이트 | `core/reasoning/modes.py:handle_chat` | new-session 첫 인사 사라짐 |

---

## 10. 한국어 요약

오늘 하루 16 PR 머지로 다음을 달성:

1. **v0.3.0 정식 release** (CHANGELOG + release notes + tag/GH release).
2. **Cognitive Layer Phase 0 + 1 + 2 핵심 PR 완료** — 본 자메스의
   "secure cognitive operating system" 차별화의 architectural 기반
   완성. trace-replay invariant 가 라이브 작동 (replay_trace.py 로
   한 trace_id 의 8 단계 reasoning 시퀀스 inspect).
3. **사이클 12 Operational UX 핵심 6 PR 완료** — 사용자 직접 보고된
   라이브 차단 4건 (N-3 / 노드 클릭 403 / 제안 칩 / 저장 spinner)
   해소 + external 격리 + 노드 편집 backend.
4. **rule #5 module-size cleanup 2건** — pipeline.py / engine.py 모두
   20 KB 게이트 안. modes.py 만 잔여 debt (별 chore PR 권장).

다음 세션은 (a) 사용자 spot-check 결과 보고 또는 (b) Phase 2 PR-7
Planner (Tool Router wiring 동반) 또는 (c) PR-O6b frontend (UI 토글 +
한글화) 중 우선 선택. 핵심 invariant 9건은 §9 표 참조.
