llm-wiki/raw/project-notes/llm-wiki-server-migration.md

---
title: LLM Wiki Server Migration
source_type: project-note
status: draft
confidence: medium
tags: [project-note, llm-wiki, architecture, application, persistence, api-design, static-analysis]
related_projects: [llm-wiki-server-migration, llm-wiki]
last_reviewed: 2026-06-29
diagrams: []
architecture_review: 2026-06-29
status_label: active
project_revision: 1
semantic_surface_exclusions:
  - artifact-registry|legacy hub has no project-local Artifact Registry; harness/source/typed-contracts.json is authoritative until migration
  - contract-gate-registry|legacy hub has no project-local Contract/Gate Registry; harness/source/typed-contracts.json is authoritative until migration
  - flow-stage-registry|legacy hub has no project-local Flow/Stage Registry; harness/source/typed-contracts.json is authoritative until migration
---

# LLM Wiki Server Migration

> Layer: `raw/project-notes/` (primary, hub) -> `/ingest` 후 검증된 사실은 `wiki/projects/` 로 추출.
> 본 문서는 현재 파일 기반 LLM Wiki 를 서버/API/DB/local runner 기반 시스템으로 이전하기 위한 프로젝트 hub 초안이다.
> 현재 등급은 `draft` 이며, 실제 구현·로컬 검증 전까지 외부 공개 가능한 프로젝트 성과로 취급하지 않는다.

## 1. 프로젝트 개요

- **한 줄 요약**: LLM Wiki Server Migration 은 현재 Markdown/Git 중심 LLM Wiki 를 개인용 서버, DB, desktop app, local agent runner 로 확장해 문서 작성·검증·상태 관리·스케줄링을 체계화하는 프로젝트다.
- **기간**: 2026-06-29 ~ in-progress.
- **현재 상태**: `active`.
- **나의 역할 / Role**: 설계자, 구현자, 사용자, 운영자.
- **저장소 / Repo**:
  - 현재 지식 저장소: `/home/donghyeon/dev/llm-wiki-private`
  - 예정 코드 저장소: 미정. 초기에는 본 repo 안의 project-note 로 요구사항을 관리하고, 구현 착수 시 별도 app repo 또는 monorepo 를 결정한다.

### 1.1 핵심 아이디어

현재 LLM Wiki 는 파일, 규칙, hook, agent skill 을 조합해 문서 품질을 관리한다. 이 방식은 Git diff 와 CLI 친화성이 강하지만, 문서 상태 추적, stale 관리, 작업 큐, dashboard, 정기 점검 같은 운영 기능은 수동 절차에 가깝다.

이 프로젝트는 LLM Wiki 를 "문서 모음"에서 "문서 운영 시스템"으로 확장한다.

```text
Desktop App / Linux App
        |
        v
Local Agent Runner  <-- locally logged-in Codex / Claude Code / other CLI
        |
        v
Personal Wiki Server API
        |
        v
DB control plane + Git/Markdown document store
```

초기 방향은 **Git/Markdown 을 문서 원본(SSOT)으로 유지하고, DB 는 index / metadata / state / job queue / audit log 로 둔다**. DB-first 는 가능하지만, 1차 MVP 에서는 diff, rollback, agent 호환성, vault portability 를 우선한다.

## 2. 문제 정의

### 2.1 현재 상태의 문제

- **문서 상태가 파일 안에 흩어져 있다**: `status`, `confidence`, `last_reviewed`, claim coverage, broken link, stale 여부를 파일마다 읽어야 한다.
- **정적 분석 결과가 저장·추적되지 않는다**: `wiki_structure_lint.py`, coverage/depth review, forbidden word grep 결과가 일회성 command output 으로 끝난다.
- **LLM 작업의 실행 경계가 약하다**: 각 CLI agent 가 파일을 직접 읽고 수정하므로, 작업 큐, 승인 상태, 실행 로그, rollback plan 이 서버 레벨에서 관리되지 않는다.
- **문서 freshness 관리가 수동이다**: 오래된 문서, stale source, broken wikilink, 미승급 `documented-only` 항목을 주기적으로 찾아야 하지만 현재는 사람이 시작해야 한다.
- **앱 UX 가 없다**: Obsidian 과 CLI 는 강하지만, 프로젝트별 상태판, review inbox, stale queue, branch-note lifecycle 을 한 화면에서 보는 도구가 없다.
- **CLI model 인증 경계가 불분명해질 수 있다**: 서버가 개인 CLI 인증을 직접 보관하면 계정 공유, token 관리, 약관 검토 위험이 커진다.

### 2.2 왜 지금 해결해야 하는가

- **트리거**: LLM Wiki 문서 수가 늘어나면서 개별 branch-note 품질뿐 아니라 전체 문서 시스템의 lifecycle 관리가 필요해졌다.
- **비용**: 상태 추적을 수동으로 계속하면 오래된 문서가 canonical 처럼 읽히거나, LLM 이 규칙을 놓친 문서를 누적시킬 수 있다.
- **기회**: local agent runner 와 서버 API 를 분리하면 개인 CLI 로그인 상태를 유지하면서도 작업 큐, 승인, 검증, audit log 를 체계화할 수 있다.

### 2.3 성공 기준

- **S1. 문서 inventory API**: `raw/`, `wiki/` 문서의 path, source_type, status, confidence, tags, related_projects, last_reviewed 를 DB index 로 조회할 수 있다.
- **S2. deterministic gate 저장**: lint/link/tag/stale 검사 결과가 DB 에 run 단위로 저장되고, 문서별 최신 gate 상태를 조회할 수 있다.
- **S3. local runner 작업 큐**: 서버가 job 을 만들고 local runner 가 pull/execute/report 하는 흐름이 동작한다. 서버는 개인 CLI token 을 저장하지 않는다.
- **S4. approval-first patch flow**: LLM 이 만든 수정안은 바로 적용되지 않고, diff/proposal 로 저장된 뒤 사용자가 승인하면 Git working tree 에 반영된다.
- **S5. scheduled stale review**: 매일 00:00 KST 에 stale 후보를 계산하고, auto-modify 가 아니라 review inbox item 을 만든다.
- **S6. Git/Markdown portability 유지**: 서버와 DB 없이도 Markdown vault 자체가 읽히고, Git history 로 복구 가능해야 한다.
- **S7. security boundary 명시**: CLI provider 별 공식 API/SDK/CLI 허용 범위, local credential 사용 방식, 금지 automation 을 별도 branch 에서 검토한다.

<!-- section-id: architecture-components -->
## 3. 시스템 아키텍처

### 3.1 아키텍처 다이어그램 (draw.io XML)

초안 단계에서는 draw.io 파일을 아직 만들지 않았다. 첫 architecture branch 에서 `raw/diagrams/llm-wiki-server-migration/architecture-overview-YYYY-MM-DD.drawio` 를 생성한다.

현재 텍스트 구조:

```text
┌───────────────────────────┐
│ Desktop App / Linux App   │
│ - dashboard               │
│ - review inbox            │
│ - document editor shell   │
└─────────────┬─────────────┘
              │ HTTPS / localhost API
              v
┌───────────────────────────┐
│ Personal Wiki Server API  │
│ - docs index API          │
│ - job queue API           │
│ - gate result API         │
│ - approval workflow       │
└───────┬─────────────┬─────┘
        │             │
        v             v
┌──────────────┐  ┌──────────────────┐
│ Postgres DB  │  │ Git/Markdown repo │
│ metadata     │  │ document SSOT     │
│ state/jobs   │  │ raw/wiki files    │
│ audit log    │  │ commits/diff      │
└──────────────┘  └──────────────────┘
        ^
        │ job pull/report
┌───────┴───────────────────┐
│ Local Agent Runner        │
│ - invokes local CLI/SDK    │
│ - no central token storage │
│ - returns proposal/diff    │
└───────────────────────────┘
```

> Diagram rule note: 위 블록은 임시 설명용 text sketch 이다. project-template 상 정식 시스템 아키텍처는 draw.io 로 작성해야 한다.

### 3.2 컴포넌트 책임 분담

| 컴포넌트 | 역할 | 기술 스택 후보 | 의존하는 외부 |
|---|---|---|---|
| Desktop App | dashboard, review inbox, document navigation, approval UI | Tauri 또는 Electron | Server API |
| Personal Wiki Server API | 문서 index, job queue, gate result, approval workflow, scheduler orchestration | FastAPI / Spring Boot / NestJS 중 택1 | DB, Git repo, local runner |
| DB | metadata, parsed frontmatter, link graph, claim graph, gate runs, job state, audit log | PostgreSQL 우선, SQLite MVP 가능 | Server API |
| Git/Markdown Store | 실제 문서 원본. `raw/`, `wiki/`, `rules/`, `templates/` 보존 | Git + Markdown | filesystem, optional remote |
| Local Agent Runner | 로컬 로그인 CLI/SDK 를 호출하고 proposal/diff 를 서버에 보고 | Rust/Go/Python/Node 중 택1 | Codex/Claude Code/other CLI |
| Static Gate Engine | frontmatter/link/tag/stale/forbidden-word/coverage precheck 실행 | 기존 Python hooks 재사용 | Git/Markdown Store |
| Scheduler | 매일 stale scan, periodic lint, source review job 생성 | Server internal scheduler 또는 OS scheduler | DB, Static Gate Engine |
| Policy Registry | provider 별 허용 실행 방식, secrets boundary, automation 금지사항 기록 | Markdown + DB indexed policy | official docs raw |

### 3.3 외부 의존성

| 외부 시스템 | 용도 | 통신 방식 | 장애 시 영향 |
|---|---|---|---|
| Local Codex / Claude Code / other CLI | 문서 초안, review, patch proposal 생성 | local process invocation 또는 official SDK | agent job 실패. deterministic gate 와 manual edit 는 유지 |
| Git remote | backup/sync/collaboration 후보 | Git protocol / HTTPS | remote sync 실패. local Git 은 계속 사용 가능 |
| Official vendor docs | CLI/API policy, SDK 사용 경계 근거 | manual archive to raw/official-docs | policy branch 가 `needs-confirmation` 으로 남음 |
| OS scheduler | local daily task trigger 후보 | cron / launchd / Windows Task Scheduler | server internal scheduler 로 대체 가능 |

### 3.4 배포 다이어그램

초기 배포는 개인 로컬 환경 기준이다.

- **Mode A: local-only MVP**
  - server: localhost
  - DB: local PostgreSQL 또는 SQLite
  - Git/Markdown: local filesystem
  - runner: same machine

- **Mode B: personal home server**
  - server/DB: private server
  - runner: user workstation
  - Git/Markdown: private Git remote + local clone
  - 주의: server 는 CLI credential 을 저장하지 않고 runner 에 job 을 위임한다.

<!-- section-id: runtime-flow -->
## 4. 핵심 시퀀스

<!-- section-id: sequence -->
### 4.1 문서 정리 작업 요청

**시나리오**: 사용자가 desktop app 에서 특정 project-note 정리를 요청하고, local runner 가 로컬 CLI 를 호출해 proposal 을 만든다.

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant App as Desktop App
    participant API as Wiki Server API
    participant DB as DB
    participant Runner as Local Agent Runner
    participant CLI as Local CLI Model
    participant Git as Git/Markdown Repo
    participant Gate as Static Gate Engine

    User->>App: 문서 정리 요청
    App->>API: POST /jobs {docPath, taskType}
    API->>DB: INSERT job(status=queued)
    Runner->>API: GET /jobs/next
    API-->>Runner: job payload
    Runner->>Git: read doc + related rules
    Runner->>CLI: generate proposal
    CLI-->>Runner: patch proposal
    Runner->>API: POST /jobs/{id}/result {proposal}
    API->>Git: apply patch to temp worktree
    API->>Gate: run lint/link/tag checks
    Gate-->>API: pass
    API->>DB: save proposal(status=needs-approval)
    API-->>App: review item created
    User->>App: approve proposal
    App->>API: POST /proposals/{id}/approve
    API->>Git: apply patch in working tree
    API->>DB: audit approved/applied
```

### 4.2 매일 00:00 stale review

**시나리오**: scheduler 가 오래된 문서를 자동 수정하지 않고 stale review item 을 만든다.

```mermaid
sequenceDiagram
    autonumber
    participant Scheduler as Scheduler
    participant API as Wiki Server API
    participant Gate as Static Gate Engine
    participant DB as DB
    participant Runner as Local Agent Runner
    participant CLI as Local CLI Model

    Scheduler->>API: trigger daily stale scan
    API->>Gate: scan last_reviewed/status/link health
    Gate-->>API: stale candidates
    API->>DB: INSERT review_items
    opt agent review enabled
        Runner->>API: pull stale-review job
        Runner->>CLI: read-only review
        CLI-->>Runner: review summary
        Runner->>API: attach review summary
        API->>DB: update review item
    end
```

### 4.3 deterministic gate before apply

**시나리오**: LLM proposal 이 적용되기 전 deterministic gate 가 최소 구조 위반을 잡는다.

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant App as Desktop App
    participant API as Wiki Server API
    participant Git as Git/Markdown Repo
    participant Gate as Static Gate Engine
    participant DB as DB

    API->>Git: apply patch to temp worktree
    API->>Gate: run lint/link/tag checks
    alt gate pass
        API-->>App: proposal ready for approval
        User->>App: approve proposal
        App->>API: POST /proposals/{id}/approve
        API->>Git: apply patch to main working tree
        API->>DB: audit status=applied
    else gate fail
        API->>DB: audit status=blocked + findings
        API-->>App: show gate failures
    end
```

## 5. 데이터 모델

초기 엔터티는 운영 상태 추적에 필요한 최소 모델로 둔다. 문서 본문은 1차 MVP 에서 Git/Markdown 이 SSOT 이며, DB 의 `document_index` 는 path 와 parsed metadata 를 저장한다.

```mermaid
erDiagram
    DOCUMENT_INDEX ||--o{ DOCUMENT_VERSION_SNAPSHOT : indexes
    DOCUMENT_INDEX ||--o{ LINK_EDGE : has
    DOCUMENT_INDEX ||--o{ GATE_RUN : checked_by
    DOCUMENT_INDEX ||--o{ REVIEW_ITEM : creates
    JOB ||--o{ JOB_EVENT : records
    JOB ||--o{ PROPOSAL : produces
    PROPOSAL ||--o{ GATE_RUN : validated_by
    PROVIDER_PROFILE ||--o{ JOB : executes

    DOCUMENT_INDEX {
        uuid id PK
        string path
        string layer
        string source_type
        string status
        string confidence
        string[] tags
        date last_reviewed
        string git_blob_sha
    }
    DOCUMENT_VERSION_SNAPSHOT {
        uuid id PK
        uuid document_id FK
        string git_commit_sha
        string content_hash
        timestamp indexed_at
    }
    LINK_EDGE {
        uuid id PK
        uuid from_document_id FK
        string to_path
        string link_type
        string status
    }
    GATE_RUN {
        uuid id PK
        uuid document_id FK
        uuid proposal_id FK
        string gate_name
        string status
        json result
        timestamp ran_at
    }
    JOB {
        uuid id PK
        string task_type
        string status
        string target_path
        uuid provider_profile_id FK
        timestamp created_at
    }
    JOB_EVENT {
        uuid id PK
        uuid job_id FK
        string event_type
        json payload
        timestamp created_at
    }
    PROPOSAL {
        uuid id PK
        uuid job_id FK
        string status
        string patch_ref
        string summary
        timestamp created_at
    }
    REVIEW_ITEM {
        uuid id PK
        uuid document_id FK
        string reason
        string status
        timestamp due_at
    }
    PROVIDER_PROFILE {
        uuid id PK
        string provider
        string execution_mode
        string credential_location
    }
```

## 6. 기술 결정

> **Legacy reference (v1).** 아래 비교표는 rationale을 보존한다. stable decision owner와 branch 상속 기준은 §6.1 registry다.

| 결정 영역 | 선택 | 검토한 대안 | 채택 이유 | 트레이드오프 | 근거 자료 |
|---|---|---|---|---|---|
| 문서 SSOT | 1차 MVP 는 Git/Markdown SSOT + DB index/control plane | DB-first, object storage-first | 현재 LLM Wiki 의 Git diff, Obsidian, CLI agent 호환성을 유지하기 위함 | DB 기반 rich editor 구현은 늦어진다 | 본 문서 §1.1 |
| DB 역할 | metadata / state / queue / audit log / gate result | 문서 본문 전체 저장 | 상태 질의와 문서 원본을 분리해 복구성을 높인다 | DB 와 Git index sync 필요 | 본 문서 §5 |
| agent 실행 | local runner 가 로컬 로그인 CLI/SDK 호출 | 서버가 provider token 보관, browser UI automation | credential centralization 을 피하고 사용자 로컬 환경을 활용한다 | runner 설치와 online 상태가 필요 | 별도 policy branch 필요 |
| 수정 적용 | proposal -> deterministic gate -> approval -> apply | LLM direct write, auto-commit | LLM 작성 오류와 규칙 위반을 apply 전에 차단한다 | 작업 속도는 느려진다 | 본 문서 §4.3 |
| scheduler | stale review item 생성, 자동 수정 금지 | 매일 자동 수정/커밋 | 개인 지식창고의 신뢰도를 유지하고 과잉 자동화를 피한다 | 사용자가 review inbox 를 처리해야 한다 | 본 문서 §4.2 |
| desktop app | Tauri 우선 검토 | Electron, web-only | 개인용 local integration, filesystem bridge, 가벼운 배포를 기대 | frontend/native boundary 설계 필요 | 별도 branch 필요 |
| server stack | 미정. FastAPI / Spring Boot / NestJS 비교 후 선택 | 단일 stack 선결정 | 이 문서는 project hub 이며, stack 결정은 별도 branch 에서 근거와 trade-off 를 박는다 | 초기 구현 착수 전 결정 필요 | `feature-server-stack-selection-contract` 예정 |

<!-- section-id: project-decisions -->
## 6.1 안정 결정 레지스트리

| Decision ID | Revision | Domain | Decision Summary | Status | Owner | Evidence |
|---|---:|---|---|---|---|---|
| `DEC-LLM-WIKI-SERVER-MIGRATION-DOCUMENT-SSOT-001` | 1 | `document-ssot` | MVP는 Git·Markdown을 document SSOT로 유지하고 DB를 index·control plane으로 사용한다 | `active` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `문서 SSOT`; §1.1 |
| `DEC-LLM-WIKI-SERVER-MIGRATION-DATABASE-ROLE-001` | 1 | `database-role` | DB는 metadata·state·queue·audit log·gate result를 저장한다 | `active` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `DB 역할`; §5 |
| `DEC-LLM-WIKI-SERVER-MIGRATION-AGENT-EXECUTION-001` | 1 | `agent-execution` | local runner가 locally authenticated CLI 또는 SDK를 호출한다 | `needs-confirmation` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `agent 실행`; 별도 policy branch 필요 |
| `DEC-LLM-WIKI-SERVER-MIGRATION-APPLY-WORKFLOW-001` | 1 | `apply-workflow` | 변경은 proposal·deterministic gate·approval·apply 순서로 적용한다 | `active` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `수정 적용`; §4.3 |
| `DEC-LLM-WIKI-SERVER-MIGRATION-SCHEDULER-001` | 1 | `scheduler` | scheduler는 stale review item만 생성하고 문서를 자동 수정하지 않는다 | `active` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `scheduler`; §4.2 |
| `DEC-LLM-WIKI-SERVER-MIGRATION-DESKTOP-RUNTIME-001` | 1 | `desktop-runtime` | desktop runtime 후보는 Tauri 우선 검토이며 채택은 확정 전이다 | `needs-confirmation` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `desktop app`; 별도 branch 필요 |
| `DEC-LLM-WIKI-SERVER-MIGRATION-SERVER-STACK-001` | 1 | `server-stack` | FastAPI·Spring Boot·NestJS 중 server stack을 선택한다 | `needs-confirmation` | [[raw/project-notes/llm-wiki-server-migration]] | §6 `server stack`; `feature-server-stack-selection-contract` 예정 |

<!-- section-id: implementation-boundaries -->
## 7. 비기능 요구사항

- **성능**: 1차 MVP 목표는 단일 사용자 기준 문서 5,000개 index rebuild 60초 이내, 단일 문서 gate run 5초 이내. 실제 측정 전까지 `planned`.
- **가용성**: local-only MVP 는 개인 도구이므로 SLO 를 두지 않는다. home server 모드에서는 server down 시 Git/Markdown 직접 편집이 fallback 이다.
- **확장성**: multi-user SaaS 는 범위 밖. 단일 사용자, 여러 device/runner 후보까지만 고려한다.
- **보안**: 서버는 provider personal CLI token 을 저장하지 않는다. local runner credential boundary 를 문서화한다. API 는 local-only 모드에서도 token 또는 local secret 을 둔다.
- **운영 / Observability**: job event, proposal lifecycle, gate result, scheduler run 을 audit log 로 남긴다.
- **재해 복구 / DR**: Git remote backup 을 1차 복구 수단으로 둔다. DB 는 재인덱싱 가능해야 한다.
- **컴플라이언스**: 개인용 도구이므로 외부 개인정보 처리 컴플라이언스는 1차 범위 밖. 단, secret/token/PII 가 문서에 들어갈 수 있으므로 local secret scan 은 별도 branch 후보로 둔다.

<!-- section-id: project-work-items -->
## 8.0 실행계획

| Work Item ID | branch slug | 완료 조건 (측정가능) | Applies Decisions | Dependencies | Status |
|---|---|---|---|---|---|
| `WI-LLM-WIKI-SERVER-MIGRATION-001` | `feature-repository-source-of-truth-contract` | Git-first·DB-first 결정표, rollback/fallback, sync invariant 5개 이상이 문서화된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-DOCUMENT-SSOT-001@1`, `DEC-LLM-WIKI-SERVER-MIGRATION-DATABASE-ROLE-001@1` | - | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-002` | `feature-server-stack-selection-contract` | 3개 stack 비교와 선택 기준 5개 이상을 근거와 함께 기록한다 | `DEC-LLM-WIKI-SERVER-MIGRATION-SERVER-STACK-001@1` | - | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-003` | `feature-document-metadata-data-model` | document_index·link_edge·gate_run·job·proposal schema가 migration 가능한 형태로 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-DOCUMENT-SSOT-001@1`, `DEC-LLM-WIKI-SERVER-MIGRATION-DATABASE-ROLE-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-001` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-004` | `feature-static-analysis-document-gates` | 기존 lint·link·tag·stale 검사가 server-side gate interface와 result schema로 노출된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-APPLY-WORKFLOW-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-003` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-005` | `feature-local-agent-runner-protocol` | registration·job pull·result·heartbeat·failure protocol이 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-AGENT-EXECUTION-001@1`, `DEC-LLM-WIKI-SERVER-MIGRATION-SERVER-STACK-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-002` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-006` | `feature-cli-provider-policy-boundary` | provider별 official CLI·SDK 경계와 금지 automation이 official source에 연결된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-AGENT-EXECUTION-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-005` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-007` | `feature-server-api-job-queue` | job·proposal·review-item API와 state machine이 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-DATABASE-ROLE-001@1`, `DEC-LLM-WIKI-SERVER-MIGRATION-APPLY-WORKFLOW-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-003` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-008` | `feature-desktop-review-workbench` | review inbox·document list·proposal diff·approve/reject 요구사항이 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-DESKTOP-RUNTIME-001@1`, `DEC-LLM-WIKI-SERVER-MIGRATION-APPLY-WORKFLOW-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-007` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-009` | `feature-scheduled-stale-review-automation` | 00:00 scan·review-item creation·auto-modify 금지 조건이 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-SCHEDULER-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-004` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-010` | `feature-git-sync-export-backup` | remote sync·DB reindex·Markdown export/import recovery 절차가 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-DOCUMENT-SSOT-001@1`, `DEC-LLM-WIKI-SERVER-MIGRATION-DATABASE-ROLE-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-001` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-011` | `feature-security-secrets-auth-boundary` | local API auth·runner secret·provider credential non-storage·audit masking 기준이 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-AGENT-EXECUTION-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-005` | `planned` |
| `WI-LLM-WIKI-SERVER-MIGRATION-012` | `feature-observability-audit-log-contract` | job·proposal·gate·scheduler event taxonomy와 minimum audit fields가 정의된다 | `DEC-LLM-WIKI-SERVER-MIGRATION-DATABASE-ROLE-001@1` | `WI-LLM-WIKI-SERVER-MIGRATION-007` | `planned` |

## 8.1 실행계획

> **Legacy reference (v1).** 기존 priority 표는 보존하며 stable ID·decision pin·dependency의 SSOT는 위 Work Item Registry다.

| branch slug | 달성 목표 조건 (측정가능) | 우선순위 | 의존 |
|---|---|---|---|
| `feature-repository-source-of-truth-contract` | Git-first vs DB-first 결정표, rollback/fallback 시나리오, sync invariant 5개 이상을 문서화한다 | P1 | - |
| `feature-server-stack-selection-contract` | FastAPI / Spring Boot / NestJS 후보 비교표와 선택 기준 5개 이상을 작성한다 | P1 | - |
| `feature-document-metadata-data-model` | `document_index`, `link_edge`, `gate_run`, `job`, `proposal` 스키마 초안을 migration 가능한 형태로 작성한다 | P2 | `feature-repository-source-of-truth-contract` |
| `feature-static-analysis-document-gates` | 기존 lint/link/tag/stale 검사를 server-side gate interface 로 감싸고 결과 schema 를 정의한다 | P2 | `feature-document-metadata-data-model` |
| `feature-local-agent-runner-protocol` | runner registration, job pull, result report, heartbeat, failure code protocol 을 정의한다 | P2 | `feature-server-stack-selection-contract` |
| `feature-cli-provider-policy-boundary` | Codex/Claude Code/other CLI 의 official API/SDK/CLI 사용 경계와 금지 automation 을 raw official docs 근거로 정리한다 | P2 | `feature-local-agent-runner-protocol` |
| `feature-server-api-job-queue` | job/proposal/review-item API endpoint 초안과 state machine 을 정의한다 | P3 | `feature-document-metadata-data-model` |
| `feature-desktop-review-workbench` | review inbox, document list, proposal diff, approve/reject 화면 요구사항을 정의한다 | P3 | `feature-server-api-job-queue` |
| `feature-scheduled-stale-review-automation` | 매일 00:00 stale scan 조건, review item 생성 규칙, auto-modify 금지 조건을 정의한다 | P3 | `feature-static-analysis-document-gates` |
| `feature-git-sync-export-backup` | Git remote sync, DB 재인덱싱, Markdown export/import 복구 절차를 정의한다 | P4 | `feature-repository-source-of-truth-contract` |
| `feature-security-secrets-auth-boundary` | local API auth, runner secret, provider credential non-storage, audit log masking 기준을 정의한다 | P4 | `feature-local-agent-runner-protocol` |
| `feature-observability-audit-log-contract` | job/proposal/gate/scheduler event taxonomy 와 최소 audit fields 를 정의한다 | P4 | `feature-server-api-job-queue` |

## 8. 묶음

<!-- GENERATED: sources:start -->
- [[raw/company-tech-blogs/deliberate-practice-software-developers-redgreencode]]
- [[raw/company-tech-blogs/senior-engineer-competency-mubin-shaikh]]
- [[raw/company-tech-blogs/skillable-hands-on-lab-structure]]
<!-- GENERATED: sources:end -->

### 8.1 브랜치

<!-- GENERATED: branches:start -->
<!-- GENERATED: branches:end -->

> generated reverse view는 child branch의 v2 contract migration 후 채운다. 현재 branch-note가 없다는 기존 설명은 그대로 유지한다.

아직 생성된 branch-note 없음. 위 §8.0 의 branch slug 는 실행계획이며, 실제 생성 전까지 wikilink 로 만들지 않는다.

### 8.2 근거 자료

Foundational source 는 아직 raw 로 archive 하지 않았다. 첫 source 수집 후보:

- OpenAI Codex official docs / manual — Codex CLI, SDK, MCP, non-interactive execution, credentials boundary 확인.
- Anthropic Claude Code official docs — CLI/SDK, automation, credentials boundary 확인.
- Google Gemini CLI / API official docs — local CLI/API boundary 확인.
- SQLite / PostgreSQL official docs — MVP DB 선택 근거.
- Tauri / Electron official docs — desktop app runtime 선택 근거.

### 8.3 오류 기록

- 아직 없음.

### 8.4 면접 준비

- 아직 없음. 후보 질문: "LLM 문서 시스템에서 Git-first 와 DB-first 를 어떻게 비교했는가?"

### 8.5 블로그·채용공고 연계 글감

- 아직 없음. 후보 글감: "개인 LLM Wiki 를 문서 운영 시스템으로 확장하기".

### 8.6 파생 wiki 문서

- canonical 검증 사실: 아직 없음.
- 관련 일반 개념: 아직 없음.
- 포트폴리오: 아직 없음.
- 블로그 글: 아직 없음.

## 9. 검증 등급

| 영역 | 등급 | 근거 |
|---|---|---|
| 아키텍처 다이어그램 | `planned` | draw.io 미작성 |
| 시퀀스 다이어그램 | `documented-only` | 본 문서 §4 Mermaid 초안 |
| 기술 결정 | `documented-only` | 본 문서 §6 초안. official docs raw archive 전 |
| 비기능 요구사항 | `planned` | 목표값만 있음. 측정 없음 |
| local runner policy | `needs-confirmation` | provider official docs 기반 별도 branch 필요 |

### 9.1 실제 구현 내용 (`actually-implemented`)

- 없음. 본 문서는 프로젝트 착수 초안이다.

### 9.2 로컬/dev 검증 (`locally-verified`)

- 없음.

### 9.3 운영 검증 (`prod-verified`)

- 없음.

### 9.4 문서/계획만 존재 (`documented-only`

- Git/Markdown SSOT + DB index/control plane 방향.
- Local Agent Runner 가 로컬 CLI/SDK 를 호출하고 서버가 provider token 을 저장하지 않는 경계.
- Approval-first patch flow.
- Scheduled stale review.
- Static gate result persistence.

## 10. 면접·외부 공개 답변 경계

### 10.1 자신 있게 답할 수 있는 범위

- 현재 LLM Wiki 의 한계와 서버/DB/control plane 으로 확장하려는 문제 정의.
- Git-first 와 DB-first 의 trade-off.
- local runner 로 개인 CLI 인증 경계를 분리하려는 설계 의도.
- 자동 수정이 아니라 proposal + approval + deterministic gate 를 기본으로 두는 이유.

### 10.2 적당히 답할 수 있는 범위

- desktop app 후보(Tauri/Electron/web-only) 비교 방향.
- PostgreSQL vs SQLite MVP 선택 방향.
- stale review scheduler 의 초기 정책.

### 10.3 답하면 안 되는 / 공식 문서 다시 확인 해야 하는 범위

- 특정 CLI provider 약관상 허용/금지의 확정 판단. 별도 official docs raw archive 와 policy branch 가 필요하다.
- 성능 수치 달성 여부. 아직 구현과 측정이 없다.
- 보안적으로 안전하다는 단정. credential boundary 설계와 검증 전이다.
- multi-user SaaS 로 확장 가능하다는 주장. 현재 범위는 개인용이다.

### 10.4 과장 금지 지점

- "서버로 옮겼다"라고 말하지 않는다. 현재는 project-note 초안이다.
- "AI 가 문서를 자동 관리한다"라고 말하지 않는다. 초기 방향은 review item/proposal 생성이다.
- "CLI provider 정책을 준수한다"라고 단정하지 않는다. official docs 확인 전에는 `needs-confirmation` 이다.
- "DB 가 문서 신뢰도를 보장한다"라고 말하지 않는다. 신뢰도는 evidence, deterministic gate, review process 로 관리한다.

## 11. 아키텍처 검토 체크리스트

- [x] 한 줄 요약 + 현재 상태 + 나의 역할 채워짐 (§1)
- [x] 측정 가능한 성공 기준 1개 이상 (§2.3)
- [ ] 아키텍처 다이어그램 (`.drawio.svg`) 1개 이상 첨부 (§3.1) — 미작성
- [ ] 다이어그램이 [[rules/diagram-standards]] v2 minimalist 통과 — 미검증
- [ ] 외부 시스템이 점선 + 회색 fill 로 시각적 구분 — draw.io 작성 후 확인
- [x] 시퀀스 다이어그램 1개 이상 (Mermaid) — §4 총 3개
- [x] 데이터 모델 ER 그림 — §5 초안
- [x] 주요 기술 결정 표에 트레이드오프 명시 (§6)
- [x] 비기능 요구사항 명시 (§7)
- [x] Branch 분해표 채워짐 (§8.0)
- [x] Cluster 섹션 작성 (§8)
- [x] 검증 등급 명시 (§9)
- [x] 면접 답변 경계 명시 (§10)
- [x] 마지막 architecture review 날짜 frontmatter `architecture_review:` 에 기록

## 12. 다이어그램 파일 관리 가이드

- 예정 위치: `raw/diagrams/llm-wiki-server-migration/`
- 첫 다이어그램 후보:
  - `architecture-overview-2026-06-29.drawio`
  - `architecture-deployment-local-2026-06-29.drawio`
  - `architecture-runner-boundary-2026-06-29.drawio`
- 생성 후 frontmatter `diagrams:` 에 활성 파일을 추가한다.

## 13. 관련 개념

- [[llm-wiki]] — 전체 vault / MOC.
- [[rules/linking-rules]] — raw/wiki upward link 와 derived gate.
- [[rules/naming-conventions]] — project-note 와 branch-note naming.
- [[rules/tag-taxonomy]] — project-note tags.
- [[rules/advisory-depth]] — 권고/설계 문서의 overclaim 방지.

## 14. 다음 단계

- [ ] `feature-repository-source-of-truth-contract` branch-note 생성.
- [ ] provider official docs 를 raw/official-docs 로 archive 한 뒤 `feature-cli-provider-policy-boundary` 작성.
- [ ] draw.io architecture overview 생성.
- [ ] server stack selection branch 에서 FastAPI / Spring Boot / NestJS 비교.
- [ ] data model branch 에서 DB-first 전환 가능성을 별도 open risk 로 정리.