# v0.3.0 — Platform Skeleton Track Handover

> **Active handover** (2026-05-13~). v0.2 가 정식 종료된 직후 신설.
> 새 Claude Code 세션이 v0.2 → v0.3 진입 이후 처음 열린다면, `CLAUDE.md`
> 다음으로 본 문서를 읽으세요.
>
> **Supersedes**: `docs/handovers/v0.2.0-platform-track.md` (audit
> trail 로 보존).

---

## 1. v0.2 종료 사실

- 2026-05-13 — Axis 6 두 번째 사용자 게이트 통과. 6 axes 모두 완료.
  v0.2 → v0.3 gate clear.
- v0.2 닫는 시점의 자산:
  - 144+ PR, 1709 tests OK
  - Change Request 기반 (`core/change_request.py` + 2 target types)
  - 정공법 3 PR (#252 / #253 / #254): 웹 학습 LLM-triple 위임 +
    UNRESOLVED sweep + 노이즈 cleanup 스크립트
  - 5축 엔지니어링 + cyber UI + monitoring stack + 모든 보안 layer

## 2. v0.3 의 정의 (recall)

`ROADMAP.md` v0.3 섹션 참조. **원래 theme: extension contract 확정**.
도메인 분화는 여전히 v1.0 이후 (CLAUDE.md rule #1 유지).

**theme 재조정 (2026-05-14)**: 사이클 8 closure 후 사용자 브리핑 결과,
v0.3 의 두 번째 메인 트랙으로 **Cognitive Layer** 가 추가됨. Plugin API
(Track C) 는 외부 기여자 트리거 부재로 v0.3.x 또는 v0.4 로 슬립.

활성 트랙 (2026-05-17 update):

| 트랙 | 정의 | 진입점 | 상태 |
|---|---|---|---|
| **A** License governance | MIT 유지 + 사전 인프라 + 모니터링 | `session-2026-05-09-license-infrastructure.md` Track A | 🟢 사이클 3 closed |
| **B** CLA Assistant | 외부 PR 받기 준비 + relicensing grant | 같은 핸드오버 Track B | ⏸ 외부 트리거 대기 |
| **C** Plugin API skeleton | `core/plugins/base.py` + `packs/general/` + manifest + dogfood gate + CI eval contract + workspace resolver | 같은 핸드오버 Track C + `docs/design/v0.3-plugin-api.md` | 🟢 **closed 2026-05-24** — 8/8 PR sequence (C2 #344 / C3 #409 / C5a #413 / C5b #418 / C6 #410 / C6.b #421 / C7 #412 / C8 #411 / C9 #419 / C10 #420). dogfood gate live; runtime invariants enforced in CI. |
| **KC** Knowledge Cascade | 5-phase 스키마 진화 + delete/modify + graph editor | `docs/design/v0.3-knowledge-cascade.md` | 🟢 **사이클 8 closed (2026-05-14)** |
| **CR-E** | self-evolution gate → Change Request 래핑 (shadow row) | `docs/handovers/v0.2.x-cr-track.md §5` + 사이클 9 below | 🟢 **closed 2026-05-24** — Stage B 4-PR sequence (#433/#434/#435/#436). dual-write permanent: 레거시 JSONL 가 authoritative, CR table 이 additive shadow. 4 locked JSONL-shape test 모두 green. |
| **Cog** Cognitive Layer | retrieval / reflection / verification / memory / multi-agent | `docs/handovers/v0.3-cognitive-layer-track.md` + ARCHITECTURE.md §5.7 | 🟢 **Phase 0+1+2 핵심 머지 (2026-05-17)** — PR-7 Planner / Phase 3 잔여 |
| **OpUX** Operational UX | 라이브 차단 4건 + external 격리 + 노드 편집 | `docs/handovers/v0.3-operational-ux-track.md` | 🟢 **사이클 12 PR-O1~O6 closed (2026-05-17)** — PR-O6b frontend / PR-O7 deferred |
| **UI-IA** UI Information Architecture | 5영역 IA 계약 + 133 API↔UI 매핑 + 코드 중복 제거 + admin.js 분할 | `docs/handovers/v0.3.x-ui-ia-track.md` | 🟡 **Phase 2 완료 (2026-05-21)** — 브라우저 검증 부채 + Phase 3 (`admin.js` 삼분할) 미착수. branch: `claude/explore-miro-integration-zKLEv` |
| **v0.3.0 release** | CHANGELOG + tag + GH release | `docs/release_notes_v0.3.0.md` | 🟢 **published (2026-05-17, #281)** |

세션 결산: `docs/handovers/v0.3.x-session-2026-05-17-closure.md`.

## 3. v0.3 진입 이후 사이클 큐 (2026-05-13 기준)

### 🔴 사이클 1 — 일상 사용 차단 해결 (v0.3 트랙과 독립, 긴급)
- **N-3** 새 세션 리프레쉬 안 됨 — 일상 인사가 안 됨, 이전 세션
  답변이 새 세션에서 나오는 현상. PR #249 (conversation continuity)
  영향 + small-talk RAG 우회 게이트 부재 추정.
- **N-1** 장기기억 후 graph cache invalidation — wiki 에 entity
  추가해도 `/graph` 가 stale, 서버 재시작해야 보임.

### 🟠 사이클 2 — 정공법 라이브 검증 (사용자 직접)
- `python scripts/cleanup_web_noise_entities.py --apply` (현재 6 후보)
- 엔비디아 자료 새로 학습 → NVIDIA org 노드 생성 확인
- "엔비디아 ↔ 조비" edge 라이브 확인

### 🟢 사이클 3 — License Track A 작은 마무리 (PR 묶음)
- A-4 `THIRD_PARTY_LICENSES.md` 단발 자동 생성 (`pip-licenses`)
- A-5 README 3종 라이선스 한 줄 통일 (`README.beginner.ko.md` 라이선스
  줄 추가 포함)
- A-6 첫 분기 모니터링 측정 기록 (`docs/LICENSE_PLAN.md §8` 2026-Q2 행)

### 🟢 사이클 4 — CLA Track B
- B-2 `docs/legal/CLA.md` 본문 초안 (+ A-3 `CONTRIBUTING.md` 동시 PR)
- B-5 `.github/workflows/cla.yml`
- B-7 `CONTRIBUTING.md` CLA 절차
- B-8 거절 응대 템플릿
- 사용자 GUI 액션: B-4 (CLA Assistant 설치), B-5 (`CLA_BOT_PAT`)

### 🟡 사이클 5 — 챗 UX 묶음 (2026-05-13 마감)
- [x] **PR #263** N-4 제안 칩 가시성 + N-5 부분 추론 mid-band 웹검색 chip.
  ✨ 제안 헤더 (mint accent + uppercase) + 신뢰도 3분기 색상 구분
  (cyan/amber/mint). i18n keys 신설 (`chat.web_chip_mid`,
  `chat.suggestions_label`).
- [x] **PR #264** N-6 장기기억 저장 모달. `jamesConfirm(opts)` 헬퍼로
  native `confirm()` 교체 → tokens.css 의 cyber 6c glass + mint
  자동 적용 (`@supports (backdrop-filter)`). WCAG dialog ARIA +
  a11y-modal.js focus trap / Escape 정합.
- 남은 후속 (별도 사이클):
  - chat.js:588 세션 reset confirm ("현재 대화를 초기화할까요?") —
    다른 flow. 단독 PR.
  - admin / workspace / graph 페이지의 confirm() — 본 사이클 표면 밖.

### 🟢 사이클 6 — 운영 도구 + v0.2.x 청소 (2026-05-13 마감)
- [x] **PR #260** `core/memory/store.py` 24 KB → 12 KB. 자연 경계 분할
  (db / conversation / summaries / store-facade). 공개 API 보존. 1714 OK.
- [x] **PR #261** `POST /admin/wiki/resolve-relations` (정공법 #253 grand sweep
  수동 트리거). admin.data gate + source_type=prod|test + shared generator
  reuse. 1720 OK.
- [x] **이미 구현 완료** (사이클 6 항목으로 잘못 적혀 있던 stale 항목):
  - `/admin/scheduler/status` GET (`server_llmwiki.py:4128`,
    `admin.metrics` gate, `is_running` / `last_retention_at` / `upcoming[]` 반환)
  - `/jobs/unschedule` POST (`server_llmwiki.py:4097`,
    `workspace.schedule` gate, `core.scheduler.unschedule_job` 위임,
    감사로그 기록)
  - 두 endpoint 모두 `tests/test_scheduler.py` 가 단위 + HTTP wiring cover.
- [x] **이미 완료** ruff Phase 2 (2026-05-11 PR). 헤더 참조: `ruff.toml`
  §"Current Pyflakes inventory" — F541 / F401 / F841 / F811 / F821 모두 0,
  ENFORCED. 현재 `ruff check .` → All checks passed!.

### 🟢 사이클 7 — Plugin API skeleton (Track C, 대규모) — **closed 2026-05-24**
> 2026-05-14 시점에는 ROI 판단으로 v0.3.x / v0.4 슬립이었지만, 2026-05-22~24
> 후속 세션에서 8-PR 시퀀스 전체가 머지됨. v0.3 Done-when 조건 중
> "dogfood test passes" 가 완전 충족된 사건.
- [x] C-2 `core/plugins/base.py` 4 Protocol + `errors.py` (#344)
- [x] C-3 `core/plugins/loader.py` + `manifest.py` + `registry.py`
      (`JAMES_PACKS=` env, SemVer) (#409)
- [x] C-5a `packs/general/` no-op overlay skeleton (#413)
- [x] C-5b 서버 startup 에 loader wire (#418) — dogfood gate live
- [x] C-6 `JAMES_WORKSPACE=` resolver (#410)
- [x] C-6.b `config.py` 가 resolver 소비 (#421, 2026-05-23) — 멀티
      인스턴스 hosting 인프라 완성
- [x] C-7 `docs/PLUGIN_AUTHORING.md` (#412)
- [x] C-8 `docs/VERSIONING.md` (SemVer + 12-month deprecation) (#411)
- [x] C-9 `.github/workflows/packs-eval.yml` + `scripts/eval_pack.py`
      (lightweight gate: manifest + slot-import + ruff) (#419)
- [x] C-10 `scripts/dogfood_check.py` + CI hook (4 runtime
      invariants) (#420)

### 🟣 사이클 11 — Cognitive Layer (Track Cognitive, v0.3 의 두 번째 메인) — **신설 (2026-05-14)**
> 사이클 8 closure 후 신설. 진입점:
> `docs/handovers/v0.3-cognitive-layer-track.md`
> + ARCHITECTURE.md §5.7. 실제 PR 작업은 사용자 추가 피드백 후.
- Phase 1 (Retrieval Intelligence): Reranker / Query rewriter / Hybrid search / Adaptive retrieval
- Phase 2 (Cognitive Middleware): Reflection loop / Verification engine (CR-E 통합) / Planner / Tool router
- Phase 3 (Memory Expansion): Episodic / Working / Long-term graph events
- Phase 4 (Controlled Multi-Agent): Orchestrator + 4 specialist 만 (anti-sprawl invariant in ARCHITECTURE.md §5.7.3)

### 🟣 사이클 8 — Knowledge Cascade (5 PR)
- [x] **Phase A — PR #266 머지 + 마이그레이션 적용 (2026-05-13)**
  - `core/relations_schema.py` (4 source roles + 헬퍼 3) — 호출 site 0, Phase B 부터 사용
  - `scripts/migrate_phase_a_sources.py` + `scripts/rollback_phase_a_sources.py`
  - **production wiki 마이그레이션 실행됨**: 213 entity files / 656 relations
    back-fill. 백업: `wiki.pre-v03-migration/` (사용자 최종 검증 후 수동 삭제)
  - 멱등 확인 (재실행 시 mutated=0, already_migrated=656)
  - 1764 tests pass (25 신규)
  - **사용자 최종 검증 대기**: `python scripts/bench.py --suite=step7 --check` +
    실사용 시나리오. 문제 시 `python scripts/rollback_phase_a_sources.py`
- [x] **Phase B — PR #269 머지 (2026-05-14)**
  - `process_document_for_entities` 가 sources 직접 작성: outgoing
    `role=extract`, inverse `role=inverse` 같은 doc_id, doc-entity self-source
  - `_build_entity_relations(..., doc_id=None, ts=None)` legacy caller 무영향
  - `create_entity_file` caller-provided sources 보존 + confidence derive
  - 1772 tests pass (8 신규)
  - 사용자 검증 PASS: 1-A (bench step7 byte-identical), 3-B (N-1 graph cache), 4 (노이즈 cleanup)
- [x] **Phase C — PR #270 머지 (2026-05-14)** `DELETE /admin/files` cascade.
  `core/cascade.py` (cascade_remove_doc_from_sources / find_orphan_entities
  강화 룰 / cascade_delete_upload / strip_uuid_prefix / backup_upload_file)
  + endpoint. 21 신규 tests → 1793 OK
- [x] **Phase E backend — PR #271 머지 (2026-05-14)** graph editor (= 사용자 요청 N-7).
  `core/graph_editor.py` (replace / append / delete + 양방향 동기화 +
  manual metadata) + 3 endpoint (`PUT/POST/DELETE /admin/graph/relation`)
  + `JAMES_GRAPH_EDIT=1` opt-in flag. 16 신규 tests → 1809 OK
- [x] **Phase E frontend UI — PR #273 머지 (2026-05-14)** `/admin/graph` 의
  edit-mode 토글 + edge 클릭 modal (sources 표시 + manual append +
  delete relation). 새 GET `/admin/graph/relation` (sources read path) +
  read_relation helper + 3 read tests. frontend: `graph_editor.js` 신규,
  graph.html + graph.js 의 hook. 1812 OK
- [x] **Phase D — 본 PR (#274)** 파일 수정 cascade. `PUT /admin/files`
  (multipart 교체) + `core/cascade.py::cascade_modify_doc` (이 doc 의
  source wipe + orphan sweep + 새 content 재 ingest) + extraction sidecar
  JSON (`uploads/<uuid>_<file>.extraction.json`) + diff_triples.
  13 신규 tests → 1822 OK

### 🟢 사이클 9 — CR-E (self-evolution → CR 래핑) — **closed 2026-05-24**
> Audit 2026-05-23 §2 가 지목한 마지막 Done-when criterion. Stage B
> 4-PR 시퀀스로 종결.
- [x] CR-E.1 (#433) — `TARGET_SELF_EVO_PATCH` / `TARGET_SELF_EVO_PROPOSAL`
      두 closed-enum target_type 추가 + no-op apply dispatcher. Zero
      behaviour change.
- [x] CR-E.2 (#434) — `/admin/patch/approve` 가 shadow CR row 생성
      (record_approval 직후) + bench-pass / apply_failed / regression
      세 outcome 모두 close. 4 source-level test 의 substring
      assertion 보존 (new lines only).
- [x] CR-E.3 (#435) — `/admin/proposals/{id}/approve|reject` 가 shadow
      CR row 생성 + close. `_bearer_username(request)` 헬퍼로 approver
      식별.
- [x] CR-E.4 (#436) — `/admin/patch/audit?include_shadow=true` 가
      legacy JSONL + CR-shadow projection 을 통합 read. Projection map:
      CR.status='open'→APPROVED, 'merged'→DEPLOYED+outcome=deployed,
      'rejected'→ROLLED_BACK+outcome=rolled_back. `_source='cr_shadow'`
      marker 로 UI 가 구분 가능.
- Dual-write permanent. 레거시 `james_patch_log.jsonl` +
  `james_evo_log.jsonl` 가 deploy timeline 의 authoritative source.
  CR row 는 additive shadow + no-op apply.
- 4 locked JSONL-shape test 모두 grenn (substring assertion window
  를 1500→2200 char 로 1회 확장만 필요).

### 🔵 사이클 10 — 다국어 호환 (N-2, 점진)
- 한국어 ↔ 영어 entity 매칭 율 측정 → synonyms.yaml 자동 보강
  + LLM 추출 프롬프트에 영/한 alias 강제

### 🟡 사이클 12 — Operational UX (2026-05-14 신설)
> 진입점: `docs/handovers/v0.3-operational-ux-track.md`.
> 라이브 사용 중 발견된 6 결손 → 7 PR 분리. cognitive layer 트랙
> (사이클 11) 과 별로 진행.
- PR-O1 노드 클릭 403 micro-fix (Authorization 헤더 누락)
- PR-O2 제안 칩 정규식 보강 (자연어 패턴 추가 + threshold ≥1)
- PR-O3 장기기억 저장 진행 spinner
- PR-O4 N-3 진짜 fix (long_ctx 새 세션 격리 — persona/user info 만 유지)
- PR-O5 비로그인 격리 (external feature matrix 좁힘 — query.internal_rag 신설)
- PR-O6 노드 편집 + 직관성 (PUT /admin/graph/node + i18n 한글화)
- PR-O7 노드 드래그 + 클릭 연결 (대규모, 별 사이클 후보)
- 사이클 11 와의 boundary: 그래프 다각적 연결 (cross-doc weak edge,
  entity alias) 은 cognitive Phase 1 으로 흡수, 본 트랙 out of scope

## 4. 운영 규칙 (변경 없음, recall)

- 도메인 분화 금지 (CLAUDE.md rule #1) — Plugin API 가 v0.3 에서 굳어
  지지만 도메인 pack 은 여전히 v0.4 부터.
- `core/retrieval/graph/reasoning` PR 은 bench numbers 필수 (rule #2).
- 모듈 size gate 20 KB (rule #5). `core/memory/store.py` 21 KB 가
  이미 위반 — 사이클 6 에서 해소.
- 자가-진화 인간 승인 게이트 무조건 유지 (rule #3).

## 5. 한국어 요약

자메스가 정식으로 **v0.3 Platform Skeleton** 단계에 진입했습니다.
v0.2 의 6축 hardening + Axis 6 두 번째 사용자 게이트가 모두 통과.
이제 외부 기여자 받기 인프라(CLA), 플러그인 계약(Plugin API),
지식 진화(Knowledge Cascade), self-evolution 통합(CR-E)이 정식
deliverable. 사이클 1 (일상 사용 차단)부터 차근차근 진행 중.
