feat: initial project setup - Merton-KMV model, data pipeline, .agents workflows

.agents/AGENT.md

@@ -0,0 +1,54 @@
+---
+description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 새 대화 시작 시 반드시 이 파일을 먼저 읽습니다.
+---
+
+# Agent Rules
+
+## Identity
+
+당신은 이 프로젝트의 시니어 개발자입니다. 지시를 정확히 따르고, 추측보다 근거를 우선합니다.
+
+## NEVER (절대 금지)
+
+1. NEVER start coding without reading relevant reference documents in `.agents/references/`
+2. NEVER guess when documentation exists — always check `.agents/references/` first
+3. NEVER repeat a failed approach — check `.agents/references/known-issues.md` first
+4. NEVER call APIs directly when helper scripts exist in `.agents/workflows/helpers/`
+5. NEVER skip the pre-task checklist defined in `.agents/workflows/pre-task.md`
+6. NEVER attempt the same failed approach more than 2 times
+7. NEVER truncate error messages — always show the full error output
+
+## ALWAYS (필수)
+
+1. ALWAYS run `.agents/workflows/pre-task.md` before any implementation task
+2. ALWAYS check `.agents/references/known-issues.md` before debugging
+3. ALWAYS cite which reference document you consulted and what you learned
+4. ALWAYS stop and ask the user if 2 consecutive attempts on the same approach fail
+5. ALWAYS use existing helper scripts instead of raw API calls
+6. ALWAYS read related existing code (minimum 3 files) before writing new code
+
+## Failure Protocol
+
+```
+1st failure → Re-read reference docs → Try DIFFERENT approach
+2nd failure (same issue) → STOP → Report diagnosis to user with:
+   - What was tried
+   - What failed
+   - Root cause hypothesis
+   - Suggested next steps
+3rd attempt on same approach → FORBIDDEN
+```
+
+## Reference Loading Order
+
+1. `.agents/AGENT.md` (this file — behavior rules)
+2. `.agents/references/known-issues.md` (past failure patterns)
+3. `.agents/references/` (project-specific knowledge)
+4. `.agents/workflows/services.md` (service credentials & protocols)
+5. `.agents/workflows/` (action procedures)
+
+## PowerShell Notes
+
+- `curl` → PowerShell에서 `Invoke-WebRequest` 별칭. **반드시 `curl.exe`** 사용
+- `npm` → 실행 정책 문제 시 `cmd /c npm` 사용
+- JSON 처리 시 `.py` 스크립트 권장 (PowerShell 이스케이핑 이슈 방지)

.agents/GUIDE.md

@@ -0,0 +1,47 @@
+# AI 에이전트 워크플로우 시스템 가이드
+
+> 이 가이드는 AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 시스템의 사용법을 설명합니다.
+
+---
+
+## 파일 구조 개요
+
+```
+.agents/
+├── AGENT.md                          ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
+├── GUIDE.md                          ← 📖 이 가이드
+├── references/                       ← 📚 프로젝트 지식 베이스
+│   ├── architecture.md               ← 아키텍처 설명
+│   ├── tech-stack.md                 ← 기술 스택 & 버전
+│   ├── conventions.md                ← 코딩 컨벤션
+│   └── known-issues.md               ← 🔴 과거 실패 기록 (핵심!)
+└── workflows/                        ← ⚙️ 행동 절차
+    ├── start.md                      ← 세션 시작 (룰 로딩 + devlog 복구)
+    ├── end.md                        ← 세션 종료 (devlog + known-issues + Vikunja + Git)
+    ├── pre-task.md                   ← 작업 전 필수 체크리스트
+    ├── debug.md                      ← 디버깅 전용 절차
+    ├── services.md                   ← 서비스 연동 정보 (API 토큰 포함)
+    ├── check-gitea.md                ← Gitea 현황 조회
+    ├── check-vikunja.md              ← Vikunja 태스크 조회
+    └── helpers/
+        ├── vikunja_helper.py         ← Vikunja API 안전 래퍼
+        └── wiki_helper.py            ← Gitea Wiki 래퍼
+```
+
+## 각 파일의 역할
+
+### 🧠 `AGENT.md` — 에이전트 헌법
+에이전트가 **모든 대화에서 따라야 하는 글로벌 규칙**입니다.
+
+### 📋 `pre-task.md` — 사전 점검 체크리스트
+모든 구현 작업 전에 실행하는 **4단계 체크리스트**.
+
+### 🔴 `known-issues.md` — 과거 실패 기록
+**가장 중요한 파일.** 에이전트가 같은 실수를 반복하지 않도록 실패를 기록합니다.
+
+### 🔧 `debug.md` — 디버깅 전용 워크플로우
+추측 기반 디버깅을 금지하는 5단계 절차.
+
+### 📓 Devlog — 세션별 작업 기록 (start.md / end.md에서 관리)
+- **Index** (`docs/devlog/YYYY-MM-DD.md`): 매 작업마다 1줄 (필수)
+- **Entry** (`docs/devlog/entries/YYYYMMDD-NNN.md`): 설계 결정/미완료/삽질 시만 (선택)

.agents/references/architecture.md

@@ -0,0 +1,34 @@
+# Architecture — EDF 프로젝트 구조
+
+## 개요
+
+주식 변동성 기반 한국 등급별 부도율 산출 (Merton-KMV 모형)
+
+## 디렉토리 구조
+
+```
+EDF/
+├── .agents/              # 에이전트 워크플로우 시스템
+├── config/
+│   └── settings.yaml     # API 키, 모델 파라미터
+├── src/
+│   ├── data/
+│   │   ├── krx_fetcher.py     # KRX 주가/시총/변동성 수집
+│   │   └── dart_fetcher.py    # DART 재무제표 수집
+│   ├── models/
+│   │   └── merton.py          # Merton DD/EDF 산출
+│   ├── calibration/           # 보정, 블렌딩 (미구현)
+│   └── validation/            # 백테스팅, 검증 (미구현)
+├── data/                 # 수집된 데이터
+├── outputs/              # 결과물
+├── docs/
+│   ├── technical_methodology.md  # 기술 문서
+│   └── devlog/           # 세션별 작업 기록
+└── requirements.txt
+```
+
+## 핵심 파이프라인
+
+```
+KRX 주가 → 변동성 계산 → Merton 풀이 → DD/EDF → Shadow Rating → 등급별 부도율
+```

.agents/references/conventions.md

@@ -0,0 +1,26 @@
+# Conventions — EDF 프로젝트 코딩 컨벤션
+
+## Python 스타일
+- PEP 8 준수
+- Type hints 사용 권장
+- Docstring: Google style
+
+## 커밋 메시지
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: data|model|calibration|validation (선택)
+```
+
+## 파일 네이밍
+- 모듈: `snake_case.py`
+- 클래스: `PascalCase`
+- 함수: `snake_case`
+- 상수: `SCREAMING_SNAKE_CASE`
+
+## 데이터 처리
+- 금액 단위: 원화 (원 단위 그대로, 변환하지 않음)
+- 날짜 형식: `YYYYMMDD` (KRX/DART 호환)
+- 변동성: 연환산 (annualized)
+- NaN 처리: `np.nan` 사용, 0 또는 빈 문자열로 대체하지 않음

.agents/references/known-issues.md

@@ -0,0 +1,8 @@
+# Known Issues — 과거 실패 기록
+
+> 이 파일은 에이전트가 같은 실수를 반복하지 않도록 실패를 기록합니다.
+> 세션 종료 시 자동으로 새 이슈를 추가합니다.
+
+---
+
+(아직 기록된 이슈가 없습니다.)

.agents/references/tech-stack.md

@@ -0,0 +1,31 @@
+# Tech Stack — EDF 프로젝트 기술 스택
+
+## 언어
+- **Python 3.10+** (miniforge3/envs/edf)
+
+## 핵심 패키지
+| 패키지 | 용도 |
+|--------|------|
+| `numpy`, `pandas` | 데이터 처리 |
+| `scipy` | Merton 비선형 방정식 풀이 (fsolve) |
+| `statsmodels` | Ordered Probit (Shadow Rating) |
+| `pykrx` | KRX 주가/시총 수집 |
+| `opendart-reader` | DART 재무제표 API |
+| `arch` | GARCH 변동성 모형 |
+| `scikit-learn` | ML 보조 모형 |
+| `matplotlib`, `plotly`, `seaborn` | 시각화 |
+| `pyyaml` | 설정 파일 |
+| `tqdm` | 프로그레스 바 |
+
+## 외부 서비스
+| 서비스 | URL | 용도 |
+|--------|-----|------|
+| DART OpenAPI | opendart.fss.or.kr | 재무제표 (무료, API 키 필요) |
+| KRX | data.krx.co.kr | 주가 데이터 (pykrx 경유) |
+| Gitea | git.variet.net | 소스코드 관리 |
+| Vikunja | plan.variet.net | 태스크 관리 |
+
+## Python 경로
+```
+C:\ProgramData\miniforge3\envs\edf\python.exe
+```

.agents/workflows/check-gitea.md

@@ -0,0 +1,35 @@
+---
+description: Gitea API로 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우
+---
+
+# Gitea 저장소 현황 조회
+
+서비스 정보는 `.agents/workflows/services.md` 참조.
+
+// turbo-all
+
+## 절차
+
+1. 최근 커밋 조회 (최신 10개):
+```powershell
+$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
+$commits = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/edf/commits?limit=10&sha=main" -Headers $h
+$commits | ForEach-Object { Write-Host "$($_.sha.Substring(0,7)) $($_.commit.message.Split("`n")[0])" }
+```
+
+2. 열린 이슈 조회:
+```powershell
+$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
+$issues = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/edf/issues?state=open&type=issues" -Headers $h
+$issues | ForEach-Object { Write-Host "#$($_.number) $($_.title)" }
+```
+
+3. Wiki 페이지 목록:
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\wiki_helper.py list
+```
+
+4. Wiki 페이지 읽기:
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\wiki_helper.py read "Architecture"
+```

.agents/workflows/check-vikunja.md

@@ -0,0 +1,40 @@
+---
+description: Vikunja API로 프로젝트 태스크 현황을 조회하는 워크플로우
+---
+
+# Vikunja 태스크 현황 조회
+
+서비스 정보는 `.agents/workflows/services.md` 참조.
+
+// turbo-all
+
+## 절차
+
+1. 전체 목록:
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py list
+```
+
+2. TODO만:
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
+```
+
+3. DONE만:
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py list done
+```
+
+4. 태스크 완료 처리 (**⚠️ 반드시 이 방법 사용 — 직접 API 호출 금지**):
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
+```
+
+5. 새 태스크 생성:
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Engine,Priority:High
+```
+
+> [!CAUTION]
+> **절대로** `Invoke-RestMethod -Method Post -Body '{"done": true}'` 같은 직접 API 호출을 사용하지 마세요.
+> `vikunja_helper.py`는 항상 GET → 기존 필드 보존 → POST 패턴을 사용합니다.

.agents/workflows/debug.md

@@ -0,0 +1,41 @@
+---
+description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에러, 안돼요, 왜 안돼, 버그, 디버그, 수정)
+---
+
+# Debug Workflow
+
+> [!IMPORTANT]
+> 추측으로 코드를 수정하지 마세요. 반드시 이 순서를 따릅니다.
+
+## 1단계: 정보 수집 (추측 금지)
+
+- [ ] 에러 메시지 **전문** 확인 (절대 잘라내지 않기)
+- [ ] 관련 로그 파일 확인
+- [ ] 환경 정보 확인 (OS, Python 버전, 의존성 버전 등)
+- [ ] 에러가 발생하는 **정확한 입력/조건** 파악
+
+## 2단계: Known Issues 확인
+
+`.agents/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
+
+> [!CAUTION]
+> **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
+
+## 3단계: 근본 원인 분석
+
+- [ ] 에러가 발생하는 **정확한 코드 위치** 확인
+- [ ] 가설을 세우고, 가설을 검증할 수 있는 **최소한의 테스트** 수행
+- [ ] 가설이 틀렸다면 **즉시 다른 가설로 전환**
+
+> [!WARNING]
+> **동일한 접근을 2회 초과 시도하지 마세요.**
+
+## 4단계: 수정 및 검증
+
+- [ ] 수정 적용
+- [ ] 동일 에러가 재현되지 않는지 확인
+- [ ] 사이드 이펙트 없는지 확인
+
+## 5단계: 기록
+
+- [ ] `known-issues.md`에 새 항목 추가

.agents/workflows/end.md

@@ -0,0 +1,108 @@
+---
+description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료)
+---
+
+# 세션 종료 프로토콜
+
+작업 완료, "끝", "마무리", "커밋해" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 0. 학습 기록 (실패/시행착오 저장)
+
+이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+
+- [ ] `.agents/references/known-issues.md`에 추가할 항목이 있는지 확인
+- [ ] 있다면 아래 포맷으로 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: ...
+- **원인**: ...
+- **해결**: ...
+- **주의**: ...
+```
+
+## 1. Devlog 기록
+
+### Index 업데이트 (필수 — 매 작업)
+
+오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다.
+
+- **파일**: `docs/devlog/YYYY-MM-DD.md`
+- **형식**:
+```markdown
+| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 |
+```
+
+> [!TIP]
+> - ✅ = 완료, 🔧 = 미완료 (다음 세션에서 이어받기)
+> - 파일이 없으면 새로 생성 (테이블 헤더 포함)
+
+### Entry 작성 (선택적 — 필요할 때만)
+
+> [!IMPORTANT]
+> Entry는 **git/Vikunja/wiki에 없는 정보**가 있을 때만 작성합니다.
+
+**Entry 파일**: `docs/devlog/entries/YYYYMMDD-NNN.md`
+
+---
+
+## 2. Vikunja 동기화
+
+> [!CAUTION]
+> **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지.
+
+### 2-1. 커밋 전수 검사
+
+이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다.
+
+```powershell
+git log --oneline -20
+```
+
+| 커밋 유형 | Vikunja 액션 |
+|-----------|-------------|
+| 기존 태스크 해당 작업 **완료** | `C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py done {ID}` |
+| 신규 작업 완료 (기존 태스크 없음) | `C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Engine,Priority:High` |
+| 작업 중 발견된 **미완료 TODO** | `C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Engine,Priority:Mid` |
+
+### 2-2. 완료 처리
+
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
+```
+
+### 2-3. 신규 태스크 생성
+
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Engine,Priority:High
+```
+
+---
+
+## 3. Git Commit & Push
+
+```powershell
+git add -A
+git status --short
+```
+```powershell
+git commit -m "커밋 메시지"
+```
+```powershell
+git push origin main
+```
+
+---
+
+## 4. 최종 체크리스트
+
+> [!WARNING]
+> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
+
+- [ ] known-issues 업데이트됨 (새 이슈가 있었다면)
+- [ ] devlog index 업데이트됨
+- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
+- [ ] git push 완료
+- [ ] 사용자에게 완료 보고

.agents/workflows/helpers/vikunja_helper.py

@@ -0,0 +1,216 @@
+"""Vikunja safe task updater — preserves existing fields when updating tasks.
+
+Usage:
+  python vikunja_helper.py done 75              # Mark task #75 as done
+  python vikunja_helper.py done 71 77 78        # Mark multiple tasks done
+  python vikunja_helper.py undone 75            # Mark task #75 as not done
+  python vikunja_helper.py comment 75 "text"    # Add comment to task #75
+  python vikunja_helper.py desc 75 "text"       # Set description (appends if exists)
+  python vikunja_helper.py create "title" "desc" --labels Engine,Priority:High
+  python vikunja_helper.py create "title" "desc" --done --labels Engine,Priority:Mid
+  python vikunja_helper.py label 75 Engine Priority:High   # Add labels to task
+  python vikunja_helper.py list                 # List all tasks
+  python vikunja_helper.py list todo            # List TODO only
+  python vikunja_helper.py list done            # List DONE only
+"""
+
+import sys
+import json
+import urllib.request
+import urllib.error
+import io
+
+# Fix Windows console encoding (cp949 → utf-8)
+if sys.stdout.encoding != "utf-8":
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+
+# ============================================================
+# ⚙️ CONFIGURATION — PROJECT_ID만 프로젝트별로 변경하세요
+# ============================================================
+API_BASE = "https://plan.variet.net/api/v1"
+TOKEN = "tk_070f8e0b715e818bb7178c3815ed5389040eddca"
+PROJECT_ID = 11                                  # EDF project
+# ============================================================
+
+HEADERS = {
+    "Authorization": f"Bearer {TOKEN}",
+    "Content-Type": "application/json",
+}
+
+# Label name → Vikunja label ID mapping
+LABEL_MAP = {
+    "Backend": 1, "Frontend": 2, "Engine": 3, "Infra": 4, "Test": 5,
+    "Priority:High": 6, "Priority:Mid": 7, "Priority:Low": 8,
+    "Agent": 17, "Tool": 18, "AI/LLM": 19,
+}
+
+
+def api_get(path: str):
+    req = urllib.request.Request(f"{API_BASE}{path}", headers=HEADERS)
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def api_post(path: str, data: dict):
+    body = json.dumps(data).encode("utf-8")
+    req = urllib.request.Request(f"{API_BASE}{path}", data=body, headers=HEADERS, method="POST")
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def api_put(path: str, data: dict):
+    body = json.dumps(data).encode("utf-8")
+    req = urllib.request.Request(f"{API_BASE}{path}", data=body, headers=HEADERS, method="PUT")
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def get_task(task_id: int) -> dict:
+    return api_get(f"/tasks/{task_id}")
+
+
+def safe_update_task(task_id: int, updates: dict) -> dict:
+    task = get_task(task_id)
+    safe_body = {
+        "title": task.get("title", ""),
+        "description": task.get("description", ""),
+        "priority": task.get("priority", 0),
+        "done": task.get("done", False),
+    }
+    safe_body.update(updates)
+    return api_post(f"/tasks/{task_id}", safe_body)
+
+
+def mark_done(task_ids: list):
+    for tid in task_ids:
+        result = safe_update_task(tid, {"done": True})
+        title = result.get("title", "?")
+        print(f"  ✅ #{tid} → done=True  [{title}]")
+
+
+def mark_undone(task_ids: list):
+    for tid in task_ids:
+        result = safe_update_task(tid, {"done": False})
+        title = result.get("title", "?")
+        print(f"  ⬜ #{tid} → done=False  [{title}]")
+
+
+def add_comment(task_id: int, comment: str):
+    result = api_put(f"/tasks/{task_id}/comments", {"comment": comment})
+    print(f"  💬 #{task_id} comment added (id={result.get('id', '?')})")
+
+
+def set_description(task_id: int, desc: str, append: bool = True):
+    task = get_task(task_id)
+    existing = task.get("description", "") or ""
+    if append and existing:
+        new_desc = existing.rstrip() + "\n\n" + desc
+    else:
+        new_desc = desc
+    result = safe_update_task(task_id, {"description": new_desc})
+    print(f"  📝 #{task_id} description updated [{result.get('title', '?')}]")
+
+
+def list_tasks(filter_: str = "all"):
+    all_tasks = []
+    page = 1
+    while True:
+        batch = api_get(f"/projects/{PROJECT_ID}/tasks?per_page=50&page={page}")
+        if not batch:
+            break
+        all_tasks.extend(batch)
+        if len(batch) < 50:
+            break
+        page += 1
+
+    if filter_ == "todo":
+        all_tasks = [t for t in all_tasks if not t["done"]]
+    elif filter_ == "done":
+        all_tasks = [t for t in all_tasks if t["done"]]
+
+    all_tasks.sort(key=lambda t: t["id"])
+    for t in all_tasks:
+        status = "✅" if t["done"] else "⬜"
+        desc = (t.get("description") or "")[:50].replace("\n", " ")
+        labels = ", ".join(l["title"] for l in (t.get("labels") or []))
+        print(f"  {status} #{t['id']:3d}  {t['title'][:40]:<40}  [{labels}]  {desc}")
+    print(f"\n  Total: {len(all_tasks)} tasks")
+
+
+def add_labels(task_id: int, label_names: list):
+    for name in label_names:
+        label_id = LABEL_MAP.get(name)
+        if not label_id:
+            print(f"  ⚠️ Unknown label '{name}'. Valid: {', '.join(LABEL_MAP.keys())}")
+            continue
+        try:
+            api_put(f"/tasks/{task_id}/labels", {"label_id": label_id})
+            print(f"  🏷️ #{task_id} + {name} (id={label_id})")
+        except Exception as e:
+            if "already" in str(e).lower() or "409" in str(e):
+                print(f"  🏷️ #{task_id} already has {name}")
+            else:
+                print(f"  ⚠️ #{task_id} label {name} failed: {e}")
+
+
+def create_task(title: str, description: str = "", done: bool = False, labels: list = None):
+    payload = {"title": title, "description": description}
+    result = api_put(f"/projects/{PROJECT_ID}/tasks", payload)
+    task_id = result["id"]
+    print(f"  ✨ #{task_id} created: {result.get('title', '?')}")
+
+    if labels:
+        add_labels(task_id, labels)
+
+    if done:
+        result = safe_update_task(task_id, {"done": True})
+        print(f"  ✅ #{task_id} → done=True")
+
+    return result
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        return
+
+    cmd = sys.argv[1].lower()
+
+    if cmd == "done":
+        ids = [int(x) for x in sys.argv[2:]]
+        mark_done(ids)
+    elif cmd == "undone":
+        ids = [int(x) for x in sys.argv[2:]]
+        mark_undone(ids)
+    elif cmd == "comment":
+        add_comment(int(sys.argv[2]), sys.argv[3])
+    elif cmd == "desc":
+        set_description(int(sys.argv[2]), sys.argv[3])
+    elif cmd == "list":
+        f = sys.argv[2] if len(sys.argv) > 2 else "all"
+        list_tasks(f)
+    elif cmd == "label":
+        if len(sys.argv) < 4:
+            print("Usage: vikunja_helper.py label TASK_ID Label1 Label2 ...")
+            return
+        add_labels(int(sys.argv[2]), sys.argv[3:])
+    elif cmd == "create":
+        title = sys.argv[2] if len(sys.argv) > 2 else ""
+        desc = sys.argv[3] if len(sys.argv) > 3 and not sys.argv[3].startswith("--") else ""
+        is_done = "--done" in sys.argv
+        labels = None
+        for i, arg in enumerate(sys.argv):
+            if arg == "--labels" and i + 1 < len(sys.argv):
+                labels = sys.argv[i + 1].split(",")
+                break
+        if not title:
+            print("Error: title is required")
+            return
+        create_task(title, desc, done=is_done, labels=labels)
+    else:
+        print(f"Unknown command: {cmd}")
+        print(__doc__)
+
+
+if __name__ == "__main__":
+    main()

.agents/workflows/helpers/wiki_helper.py

@@ -0,0 +1,100 @@
+"""Gitea Wiki helper: list, read, create, update wiki pages.
+
+Usage:
+  wiki_helper.py list                     — list all pages
+  wiki_helper.py read <title>             — read a page
+  wiki_helper.py create <title> <file>    — create a page from file
+  wiki_helper.py update <title> <file>    — update a page from file
+"""
+import sys, io, json, base64, urllib.request, urllib.error
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+# ============================================================
+# ⚙️ CONFIGURATION — GITEA_REPO만 프로젝트별로 변경하세요
+# ============================================================
+GITEA_BASE_URL = "https://git.variet.net"
+GITEA_OWNER = "Variet"
+GITEA_REPO = "edf"                                # ← EDF project
+GITEA_TOKEN = "3a01b4b15a39921572e64c413353e870d4d2161b"
+# ============================================================
+
+BASE = f"{GITEA_BASE_URL}/api/v1/repos/{GITEA_OWNER}/{GITEA_REPO}/wiki"
+HEADERS = {"Authorization": f"token {GITEA_TOKEN}", "Content-Type": "application/json"}
+
+def _req(method, path, data=None):
+    url = f"{BASE}{path}"
+    body = json.dumps(data).encode() if data else None
+    req = urllib.request.Request(url, data=body, headers=HEADERS, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        err = e.read().decode()
+        print(f"  ⚠️ HTTP {e.code}: {err}")
+        return None
+
+def _find_sub_url(title):
+    pages = _req("GET", "/pages")
+    if pages:
+        for p in pages:
+            if p.get("title", "").lower() == title.lower():
+                return p.get("sub_url", title)
+    return title
+
+def list_pages():
+    pages = _req("GET", "/pages")
+    if pages:
+        print(f"=== {len(pages)} Wiki Pages ===")
+        for p in pages:
+            print(f"  {p.get('title', '?')}")
+    return pages
+
+def read_page(title):
+    sub = _find_sub_url(title)
+    page = _req("GET", f"/page/{sub}")
+    if page and page.get("content_base64"):
+        content = base64.b64decode(page["content_base64"]).decode("utf-8")
+        return content
+    return None
+
+def create_page(title, content):
+    data = {
+        "title": title,
+        "content_base64": base64.b64encode(content.encode()).decode(),
+    }
+    result = _req("POST", "/new", data)
+    if result:
+        print(f"  ✅ Created wiki page: {title}")
+    return result
+
+def update_page(title, content):
+    sub = _find_sub_url(title)
+    data = {
+        "title": title,
+        "content_base64": base64.b64encode(content.encode()).decode(),
+    }
+    result = _req("PATCH", f"/page/{sub}", data)
+    if result:
+        print(f"  ✅ Updated wiki page: {title}")
+    return result
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "list"
+
+    if cmd == "list":
+        list_pages()
+    elif cmd == "read" and len(sys.argv) > 2:
+        content = read_page(sys.argv[2])
+        if content:
+            print(content[:5000])
+        else:
+            print(f"  Page '{sys.argv[2]}' not found")
+    elif cmd == "create" and len(sys.argv) > 3:
+        with open(sys.argv[3], "r", encoding="utf-8") as f:
+            create_page(sys.argv[2], f.read())
+    elif cmd == "update" and len(sys.argv) > 3:
+        with open(sys.argv[3], "r", encoding="utf-8") as f:
+            update_page(sys.argv[2], f.read())
+    else:
+        print("Usage: wiki_helper.py list|read <title>|create <title> <file>|update <title> <file>")

.agents/workflows/pre-task.md

@@ -0,0 +1,39 @@
+---
+description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트 (pre-task, 준비, 시작 전, 계획, 구현)
+---
+
+# Pre-Task Checklist
+
+> [!IMPORTANT]
+> 코딩을 시작하기 전에 반드시 이 체크리스트를 순서대로 완료하세요.
+> 체크리스트를 건너뛸 경우 불필요한 시행착오가 발생합니다.
+
+## 1단계: 요구사항 정리
+
+- [ ] 유저 요청을 구체적 작업 항목으로 분해
+- [ ] 변경 범위(scope)를 명확히 정의 (영향받는 파일/모듈)
+- [ ] 성공 기준(acceptance criteria) 확인
+
+## 2단계: 레퍼런스 확인 (추측 금지)
+
+- [ ] `.agents/references/architecture.md` — 현재 아키텍처 확인
+- [ ] `.agents/references/tech-stack.md` — 기술 스택 및 버전 확인
+- [ ] `.agents/references/conventions.md` — 코딩 컨벤션 확인
+- [ ] `.agents/references/known-issues.md` — 과거 실패 패턴 확인
+- [ ] 관련 기존 코드 최소 3개 파일 읽기
+
+> [!CAUTION]
+> 레퍼런스 문서가 존재하는 주제에 대해 추측하지 마세요.
+> 문서가 없으면 유저에게 확인을 요청하세요.
+
+## 3단계: 계획 수립
+
+- [ ] 변경할 파일 목록 작성
+- [ ] 의존성 순서 파악 (어떤 파일부터 수정해야 하는가?)
+- [ ] 리스크 식별 (어디서 실패할 가능성이 높은가?)
+- [ ] 테스트 방법 결정 (어떻게 검증할 것인가?)
+
+## 4단계: 유저 확인
+
+- [ ] 계획을 유저에게 보고하고 승인받기 (변경 파일 3개 이상인 경우)
+- [ ] 작은 변경은 바로 실행하되, 변경 내용을 명확히 설명

.agents/workflows/services.md

@@ -0,0 +1,106 @@
+---
+description: 프로젝트 연동 서비스 URL, API 키, 프로젝트 정보 참조
+---
+
+# 서비스 연동 정보
+
+> [!CAUTION]
+> 이 파일에는 API 토큰이 포함되어 있습니다. 프라이빗 레포에서만 사용하세요.
+
+## 로컬 환경
+
+| 항목 | 값 |
+|------|-----|
+| **Python** | `C:\ProgramData\miniforge3\envs\edf\python.exe` (**항상 이 경로 사용**) |
+| **Shell** | PowerShell (`curl` = `Invoke-WebRequest` 별칭이므로 반드시 **`curl.exe`** 사용) |
+
+## Gitea (Git Repository)
+
+| 항목 | 값 |
+|------|-----|
+| **Base URL** | `https://git.variet.net` |
+| **API Base** | `https://git.variet.net/api/v1` |
+| **Repo** | `Variet/edf` |
+| **Token** | `3a01b4b15a39921572e64c413353e870d4d2161b` |
+| **Auth Header** | `-H "Authorization: token 3a01b4b15a39921572e64c413353e870d4d2161b"` |
+
+## Vikunja (Task Management)
+
+| 항목 | 값 |
+|------|-----|
+| **Base URL** | `https://plan.variet.net` |
+| **API Base** | `https://plan.variet.net/api/v1` |
+| **Project ID** | `11` |
+| **Token** | `tk_070f8e0b715e818bb7178c3815ed5389040eddca` |
+| **Auth Header** | `-H "Authorization: Bearer tk_070f8e0b715e818bb7178c3815ed5389040eddca"` |
+
+## Vikunja 태스크 조회
+
+> [!TIP]
+> 태스크 목록은 항상 라이브 조회를 사용합니다. 하드코딩된 매핑은 유지하지 않습니다.
+
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
+```
+
+## AI 작업 프로토콜
+
+> [!IMPORTANT]
+> 아래 규칙은 모든 작업에 자동 적용됩니다. 유저가 별도 지시하지 않아도 따릅니다.
+
+### Vikunja = Single Source of Truth (SSOT)
+
+- **Vikunja가 유일한 작업 현황 관리 도구**입니다.
+- 로컬 `task.md`는 현재 대화 내 세부 체크리스트용으로만 사용합니다.
+- 새 TODO 발견 시 → Vikunja에 태스크 생성 (로컬 파일에만 적는 것은 금지)
+- 작업 완료 시 → Vikunja 태스크 완료 처리 (로컬 체크만 하는 것은 금지)
+
+### Vikunja 태깅 규칙
+
+태스크 생성 시 반드시 아래 라벨을 적절히 부여합니다:
+
+**영역 라벨 (필수, 1개 이상):**
+
+| ID | 라벨 | 적용 대상 |
+|:--:|-------|-----------:|
+| 1 | `Backend` | 서버, DB, API |
+| 2 | `Frontend` | UI, 웹 프론트엔드 |
+| 3 | `Engine` | 핵심 엔진/로직 |
+| 4 | `Infra` | Docker, CI/CD, 모니터링 |
+| 5 | `Test` | 테스트, E2E |
+
+**우선순위 라벨 (필수, 1개):**
+
+| ID | 라벨 | 기준 |
+|:--:|-------|------:|
+| 6 | `Priority:High` | 핵심 기능 미완성, 블로커 |
+| 7 | `Priority:Mid` | 기능 개선, UX 향상, 리팩터링 |
+| 8 | `Priority:Low` | nice-to-have, 문서, 코드 정리 |
+
+### 작업 시작 시
+1. `git pull` 으로 최신 코드 동기화
+2. Vikunja 태스크 조회 (`/check-vikunja`) → 관련 태스크 ID 확인
+3. 관련 태스크가 있으면 Vikunja에서 진행중 표시
+4. 관련 태스크가 없으면 Vikunja에 새 태스크 생성 (태깅 규칙 준수)
+
+### 작업 중
+5. 의미 있는 단위마다 자주 커밋 (대규모 변경을 한번에 커밋하지 않음)
+6. 커밋 메시지 규칙:
+   - `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, `ci:` 접두사 사용
+   - 관련 Vikunja 태스크가 있으면 `#task-{ID}` 참조 포함
+
+### 작업 완료 시
+7. 모든 변경사항 커밋 + `git push`
+8. Vikunja 태스크 완료 처리 (**반드시 `vikunja_helper.py` 사용**):
+   ```powershell
+   C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
+   ```
+
+> [!CAUTION]
+> **직접 `Invoke-RestMethod -Body '{"done": true}'` 사용 금지!**
+> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다.
+
+## PowerShell 주의사항
+
+- `curl` → PowerShell에서 `Invoke-WebRequest`의 별칭. **반드시 `curl.exe`** 사용
+- JSON 파이프 파싱 시 PowerShell 이스케이핑 문제 → `.py` 스크립트 파일로 만들어 실행 권장

.agents/workflows/start.md

@@ -0,0 +1,66 @@
+---
+description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
+---
+
+# 세션 시작 프로토콜
+
+새 대화 시작, "continue", "이어서", "작업 시작" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 절차
+
+### 0. 에이전트 룰 & 맥락 로딩 (자동)
+
+`.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
+`.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다.
+`.agents/workflows/services.md`의 **로컬 환경** 섹션을 읽고 Python 경로 등 환경 설정을 확인합니다.
+
+### 1. Devlog 맥락 복구
+
+오늘 + 어제 devlog index를 읽고 최근 작업 흐름을 파악합니다.
+
+```powershell
+$today = Get-Date -Format "yyyy-MM-dd"
+$yesterday = (Get-Date).AddDays(-1).ToString("yyyy-MM-dd")
+if (Test-Path "docs\devlog\$today.md") {
+    Write-Host "=== Devlog: $today ==="
+    Get-Content "docs\devlog\$today.md"
+} elseif (Test-Path "docs\devlog\$yesterday.md") {
+    Write-Host "=== Devlog: $yesterday (no entry for today yet) ==="
+    Get-Content "docs\devlog\$yesterday.md"
+} else {
+    Write-Host "=== No recent devlog found ==="
+}
+```
+
+미완료(🔧) 항목이 있으면 해당 entry 파일을 읽어 이어받기 맥락을 확보합니다:
+- Entry 경로: `docs/devlog/entries/YYYYMMDD-NNN.md`
+
+### 2. Git 상태 확인
+
+```powershell
+git status --short
+```
+```powershell
+git log --oneline -5
+```
+
+### 3. Vikunja TODO 태스크
+
+```powershell
+C:\ProgramData\miniforge3\envs\edf\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
+```
+
+### 4. 종합 보고
+
+결과를 종합하여 사용자에게 보고:
+- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반)
+- TODO 태스크 목록 (라벨 + 우선순위)
+- 다음 작업 제안
+
+**우선순위 판단 기준** (라벨만으로 판단 금지):
+- P0: 최근 커밋에서 스키마/모델/인터페이스 변경 → 연쇄 영향 점검
+- P1: 서버 기동/API 응답 장애
+- P2: 기능 미완성/UX 개선
+- P3: 정확도 향상, 신규 기능, CI/CD, 문서 정리