# web-ai V1 → signal_v1 Rename Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** `web-ai/` 루트의 모든 V1 자산 (main_server.py + modules/ + data/ + tests/ + 진입점 스크립트 + 문서 + 로그) 을 `web-ai/signal_v1/` 안으로 atomic mv 하고, web-ai 루트에 신규 가이드 (`CLAUDE.md`, `start.bat`) 추가. V2 (`signal_v2/`) 추가 전 신/구 격리.

**Architecture:** 단일 atomic commit (stock-lab → stock graduation 과 동일 패턴). `git mv` 로 history 보존, `load_dotenv()` 호출만 경로 명시. cwd 기반 V1 코드라 import 변경 0. Phase 6 deprecation 시 `rm -rf signal_v1/` 단순화.

**Tech Stack:** git mv / Python load_dotenv path 갱신 / pytest 회귀 확인

**Spec:** `web-ui/docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md`

---

## 파일 구조 (Task 2 후)

```
web-ai/
├── .env                    ← 그대로 (V1 + V2 공유)
├── .gitignore              ← 그대로
├── CLAUDE.md               ← 신규 (web-ai 레벨 가이드)
├── start.bat               ← 신규 (signal_v1 진입 wrapper)
├── signal_v1/              ← 신규 디렉토리
│   ├── CLAUDE.md           ← 기존 V1 가이드 (mv)
│   ├── KIS_SETUP.md
│   ├── README.md
│   ├── main_server.py      ← load_dotenv 경로 명시 갱신
│   ├── warmup_and_restart.py  ← load_dotenv 경로 명시 갱신
│   ├── watchlist_manager.py
│   ├── backtester.py
│   ├── backtest_runner.py
│   ├── theme_manager.py
│   ├── start.bat           ← 사용 안 함 (cleanup 안 함, 향후)
│   ├── modules/            ← 전체
│   ├── data/               ← 전체 (runtime data 보존)
│   ├── tests/              ← 전체
│   └── (log/json 파일들)
└── (signal_v2/ 는 Phase 2 spec)
```

---

## Task 1: Atomic refactor (사전 점검 + git mv + 신규 파일 + 검증 + commit)

**Files:**
- Source repo: `C:\Users\jaeoh\Desktop\workspace\web-ai` (별도 Gitea repo: `ai-trade.git`, branch `main`)
- Create: `web-ai/signal_v1/` (디렉토리)
- Create: `web-ai/CLAUDE.md` (신규)
- Create: `web-ai/start.bat` (신규)
- Move (git mv): web-ai 루트의 모든 V1 자산 → signal_v1/
- Modify: `web-ai/signal_v1/main_server.py` (load_dotenv 명시 경로)
- Modify: `web-ai/signal_v1/warmup_and_restart.py` (load_dotenv 명시 경로)
- (필요 시) Modify: `signal_v1/modules/config.py` 또는 다른 load_dotenv 위치

- [ ] **Step 1: 사전 — 자동매매 봇 정지 확인 + git status clean**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
git status
```
Expected: `nothing to commit, working tree clean`. 만약 dirty 면 implementer 는 BLOCKED 보고. 사용자가 stash 또는 commit 처리.

또한: V1 자동매매 봇이 실행 중이면 mv 도중 파일 잠금 위험. PowerShell:
```powershell
Get-Process python -ErrorAction SilentlyContinue | Select-Object Id, ProcessName, StartTime
```
실행 중 Python 프로세스 발견 시 사용자에게 종료 요청. (장외 시간대에 작업 가정.)

- [ ] **Step 2: 사전 grep — load_dotenv 호출 위치 파악**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
grep -rn "load_dotenv" --include="*.py" .
```
Expected: 1~3개 hit. 각 hit 의 파일 경로 기록 (Step 6 에서 갱신). 일반적으로 main_server.py, warmup_and_restart.py, modules/config.py 중 1~2곳에 있음.

만약 hit 0 이면 V1 이 `.env` 를 다른 방식 (예: pydantic-settings) 으로 로드. 코드 경로 추가 grep:
```bash
grep -rn "BaseSettings\|env_file\|\.env" --include="*.py" .
```
어느 방식이든 cwd 가 signal_v1/ 으로 바뀌면 `.env` 가 parent (`web-ai/.env`) 에 있다는 사실을 코드가 알아야 함.

- [ ] **Step 3: 사전 baseline — 현 pytest 통과 개수 측정**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
python -m pytest tests/unit -q 2>&1 | tail -3
```
Expected output 형태: `N passed in Xs` (또는 `N passed, M warnings ...`). N 값을 baseline 으로 기록 (Step 13 에서 비교).

만약 baseline 자체가 실패면 implementer 는 DONE_WITH_CONCERNS 보고 — 사용자 결정 (pre-existing failure 라면 무시하고 진행 가능).

- [ ] **Step 4: signal_v1 디렉토리 생성**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
mkdir signal_v1
```
Verify:
```bash
ls -d signal_v1
```
Expected: `signal_v1`

- [ ] **Step 5: git mv 실행 (V1 자산 모두)**

다음 항목을 모두 `signal_v1/` 안으로 이동. `git mv` 사용 (history 보존):

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai

# 진입점 + 스크립트
git mv main_server.py signal_v1/
git mv warmup_and_restart.py signal_v1/
git mv watchlist_manager.py signal_v1/
git mv backtester.py signal_v1/
git mv backtest_runner.py signal_v1/
git mv theme_manager.py signal_v1/
git mv start.bat signal_v1/

# 문서 (현 V1 가이드)
git mv CLAUDE.md signal_v1/
git mv KIS_SETUP.md signal_v1/
git mv README.md signal_v1/

# 디렉토리
git mv modules signal_v1/
git mv data signal_v1/
git mv tests signal_v1/

# 로그 / IPC / 캐시
git mv bot_ipc.json signal_v1/ 2>/dev/null || true
git mv bot_output.log signal_v1/ 2>/dev/null || true
git mv daily_launcher.log signal_v1/ 2>/dev/null || true
git mv server.log signal_v1/ 2>/dev/null || true
git mv telegram_bot.log signal_v1/ 2>/dev/null || true
git mv warmup.log signal_v1/ 2>/dev/null || true
```

`__pycache__/` 는 gitignore 이므로 git mv 불가능. 단순 mv:
```bash
mv __pycache__ signal_v1/ 2>/dev/null || true
```

Verify:
```bash
git status --short | head -30
ls signal_v1/
ls
```
Expected: `signal_v1/` 안에 모든 V1 자산이 있고, web-ai 루트에는 `.env`, `.gitignore`, `signal_v1/` 만 (still untracked: none yet for new files).

- [ ] **Step 6: load_dotenv 경로 명시 갱신**

Step 2 에서 식별한 각 `load_dotenv()` 호출을 명시 경로로 변경. 가장 빈도 높은 패턴 (main_server.py 의 시작 부분):

기존 (cwd 기준):
```python
from dotenv import load_dotenv
load_dotenv()
```

신규 (명시 경로, signal_v1 의 parent = web-ai 루트):
```python
from pathlib import Path
from dotenv import load_dotenv

# web-ai/.env (signal_v1/ 의 parent) 명시 로드
load_dotenv(Path(__file__).parent.parent / ".env")
```

Step 2 에서 식별한 모든 위치에 동일 패턴 적용. 만약 V1 이 `BaseSettings` (pydantic) 사용 시:
```python
class Settings(BaseSettings):
    class Config:
        env_file = str(Path(__file__).parent.parent / ".env")
```

만약 V1 이 그냥 `os.getenv(...)` 만 쓰고 어딘가에서 명시적으로 load 하지 않는다면 (uvicorn 이 시작 시 cwd 의 .env 를 자동 로드 시) — 시작 wrapper (`web-ai/start.bat`) 가 `cd signal_v1` 후 실행하면 cwd=signal_v1 → `.env` 못 찾음. 해결: Step 7 의 `start.bat` 에서 명시적으로 `cd /d "%~dp0"` (= web-ai 루트) 후 `python signal_v1/main_server.py` 실행.

근데 그러면 main_server.py 안의 다른 상대 경로 (`data/kis_token.json` 등) 가 cwd=web-ai 일 때 `web-ai/data/kis_token.json` 을 찾음 → 잘못된 경로. 

**결정**: cwd 는 `signal_v1/` 으로 두고 `load_dotenv(Path(__file__).parent.parent / ".env")` 명시. 다른 상대 경로는 cwd=signal_v1 기준이라 `data/...` 그대로 작동.

각 갱신 후 git status:
```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
git status --short | head -10
```
Expected: signal_v1/main_server.py 등 modified 표시.

- [ ] **Step 7: 신규 파일 — web-ai/CLAUDE.md**

Create `web-ai/CLAUDE.md`:

```markdown
# web-ai — Workspace 가이드

Windows AI 머신 (AMD 9800X3D + RTX 5070 Ti) 의 두 시그널 파이프라인 컨테이너.

## 디렉토리 구조

| 경로 | 역할 | 상태 |
|------|------|------|
| `signal_v1/` | V1 자체 자동매매 시스템 (main_server.py + Trading Bot + Telegram Bot + LSTM + Ollama + KIS 자동주문) | 운영 중. Confidence Signal Pipeline V2 Phase 6 에서 deprecation 예정 |
| `signal_v2/` | V2 신호 파이프라인 (stock pull worker + Chronos-2 + signal API client) | Phase 2 에서 신설 |
| `.env` | V1 + V2 환경변수 공유 | KIS_*, TELEGRAM_*, STOCK_API_URL, WEBAI_API_KEY 등 |
| `start.bat` | V1 진입 (signal_v1 디렉토리 안 main_server.py 실행) | V2 별도 start 스크립트는 signal_v2/start.bat |

## 운영 가이드

- V1 시작: `start.bat` 또는 `cd signal_v1 && python main_server.py`
- V2 시작 (Phase 2 이후): `cd signal_v2 && python -m uvicorn main:app --port 8001`
- 둘 다 동시 실행 가능 (포트 분리: V1=8000, V2=8001)

## Phase 진행 상태 (Confidence Signal Pipeline V2)

`web-ui/docs/superpowers/specs/2026-05-15-confidence-signal-pipeline-v2-architecture.md` 참조.

자세한 V1 가이드는 `signal_v1/CLAUDE.md` 참조.
```

- [ ] **Step 8: 신규 파일 — web-ai/start.bat**

Create `web-ai/start.bat`:

```bat
@echo off
cd /d "%~dp0\signal_v1"
python main_server.py
```

- [ ] **Step 9: git add 신규 파일**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
git add CLAUDE.md start.bat
git add signal_v1/main_server.py signal_v1/warmup_and_restart.py  # load_dotenv 갱신
# 추가로 갱신한 다른 .py 파일이 있으면 모두 add
```

git status 점검:
```bash
git status
```
Expected: 모든 git mv + 신규 + modify 변경이 staged 상태.

- [ ] **Step 10: 잔여 grep — `from web-ai` 같은 잘못된 import 0건 확인**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
grep -rn "from web-ai\|import web-ai" --include="*.py" signal_v1/
```
Expected: 0 lines.

또한 V1 코드 안에 hardcoded 절대 경로 (예: `C:\Users\jaeoh\Desktop\workspace\web-ai\data\...`) 검사:
```bash
grep -rn "web-ai.data\|web-ai/data\|web-ai\\\\data" --include="*.py" signal_v1/
```
Expected: 0 lines.

만약 hit 있으면 implementer 는 DONE_WITH_CONCERNS 보고, 사용자가 조정.

- [ ] **Step 11: signal_v1 안에서 pytest 자동 검증**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai/signal_v1
python -m pytest tests/unit -q 2>&1 | tail -5
```
Expected: Step 3 의 baseline 과 동일한 PASS 개수 (회귀 없음).

만약 import 오류 (`ModuleNotFoundError: No module named 'modules'`) 가 발생하면 conftest.py 가 sys.path 를 수정하지 않을 가능성. 확인:
```bash
cat tests/unit/conftest.py | head -20
```
필요 시 `sys.path.insert(0, str(Path(__file__).parent.parent.parent))` 추가. 단, 기존 conftest 가 cwd 기반이면 cwd=signal_v1 에서 작동해야 함.

만약 다른 failure 면 BLOCKED 보고 — 사용자 진단.

- [ ] **Step 12: 잠시 후 다시 git status — 추가 untracked 없는지 확인**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
git status
```
Expected: 모든 변경이 staged. 만약 새 untracked (pytest cache 등) 있으면 .gitignore 패턴 또는 무시.

- [ ] **Step 13: 단일 commit**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ai
git commit -m "$(cat <<'EOF'
refactor: web-ai V1 assets → signal_v1/ (graduation prep)

Atomic mv of root V1 assets (main_server.py + modules/ + data/ +
tests/ + entry scripts + docs + logs) into signal_v1/ subdirectory.
load_dotenv() updated to load web-ai/.env explicitly via Path.

Adds web-ai/CLAUDE.md (workspace guide) and web-ai/start.bat
(signal_v1 entry wrapper). Prepares for signal_v2/ Phase 2.

Tests: signal_v1/tests/unit baseline preserved (no regression).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

Verify:
```bash
git log -1 --stat
```
Expected: 1 commit, 다수 rename + 2 신규 (CLAUDE.md / start.bat) + 1-3 modified (load_dotenv 위치).

## Reporting

When done, report:
- DONE: commit SHA, baseline test count (Step 3) + post-mv count (Step 11), 자동 grep 결과 (0 lines).
- DONE_WITH_CONCERNS: implementation 됐지만 hardcoded path / pre-existing test fail 등 발견 — 상세 보고.
- NEEDS_CONTEXT: load_dotenv 패턴이 spec 예상과 다름, 또는 conftest 추가 fix 필요 등.
- BLOCKED: working tree dirty / pytest baseline 자체 실패 / git mv 충돌.

---

## Task 2: 사용자 수동 — 운영 검증 + push

**This task requires user action. Pause and request user to perform.**

- [ ] **Step 1: V1 자동매매 봇 정상 시작 검증**

사용자가 PowerShell 에서:
```powershell
cd C:\Users\jaeoh\Desktop\workspace\web-ai
.\start.bat
```

기대 출력 (수십 줄):
- `Config.validate()` 성공 (환경변수 누락 없음)
- KIS OAuth `access_token` 발급 (또는 cached token 로드)
- Telegram Bot started + `Conflict` 없음
- ProcessWatchdog 시작
- Uvicorn 0.0.0.0:8000 listening
- 봇 사이클 (장중이면) 또는 idle (장외)

만약 `FileNotFoundError: .env` 또는 KIS auth 실패 시 — load_dotenv 경로 오류. Task 1 으로 돌아가 Step 6 조정.

- [ ] **Step 2: Telegram /status 명령 응답 검증**

사용자가 텔레그램에서 `/status` 명령. 봇이 정상 응답하면 IPC + SharedMemory + Telegram Bot 모두 정상.

- [ ] **Step 3: 30분 관측**

콘솔 또는 telegram_bot.log 에 에러 없음 + Watchdog 30초 간격 health check PASS 확인.

만약 자식 프로세스 (Trading Bot / Telegram Bot) 가 자동 종료 → restart loop → 재실패 시 Task 1 으로 돌아가 진단.

- [ ] **Step 4: git push (사용자, Gitea 자격증명)**

```powershell
cd C:\Users\jaeoh\Desktop\workspace\web-ai
git push
```

만약 자격증명 실패 시 사용자가 수동으로 처리 (메모리 `feedback_nas_deploy_paths.md` 의 Gitea 자격증명 패턴).

- [ ] **Step 5: 결과 보고 (사용자 → 컨트롤러)**

- Step 1 (start.bat 시작): PASS / FAIL — 첫 에러 메시지 공유
- Step 2 (/status 응답): PASS / FAIL
- Step 3 (30분 관측): PASS (no errors) / FAIL — 관측된 에러
- Step 4 (push): PASS / FAIL

전부 PASS 시 Task 2 완료 → Phase 2 brainstorming 재개 (이미 6 결정 + 디자인 섹션 1-2 OK).

---

## Self-Review

**1. Spec coverage:**

| Spec § | 요구사항 | Plan task |
|--------|----------|----------|
| §2 포함 (V1 자산 mv) | Task 1 Step 5 ✅ |
| §2 포함 (web-ai/CLAUDE.md 신규) | Task 1 Step 7 ✅ |
| §2 포함 (web-ai/start.bat 신규) | Task 1 Step 8 ✅ |
| §2 범위 외 (Python import 변경 없음) | Task 1 Step 10 의 grep 으로 검증 ✅ |
| §3.3 web-ai/CLAUDE.md 정확한 내용 | Task 1 Step 7 — 동일 markdown 본문 포함 ✅ |
| §3.3 web-ai/start.bat 정확한 내용 | Task 1 Step 8 — 동일 bat 본문 포함 ✅ |
| §3.4 load_dotenv 경로 갱신 | Task 1 Step 2 (grep) + Step 6 (갱신) ✅ |
| §4 작업 순서 (사전 검토 → mv → 검증 → push → 사용자 검증) | Task 1 Step 1-13 + Task 2 ✅ |
| §5 위험 (.env 로드 실패, 자동매매 중단 등) | Task 2 Step 1 의 first-start verification + load_dotenv 명시 ✅ |
| §6.1 자동 검증 (pytest + grep) | Task 1 Step 3 (baseline) + Step 11 (post-mv) + Step 10 (grep) ✅ |
| §6.2 수동 검증 (start.bat + /status + 30분 관측) | Task 2 Step 1-3 ✅ |
| §8 DoD 8 항목 | 전체 (Task 1 + Task 2 합) ✅ |

No gaps.

**2. Placeholder scan:** No "TBD" / "implement later". load_dotenv 갱신은 Step 2 grep 결과에 의존하지만, Step 6 에 정확한 갱신 패턴 (2 코드 예시) 포함 — placeholder 아님.

**3. Type consistency:** N/A (refactor only, 새 함수/타입 0). 모든 step 의 명령어와 파일 경로 일관 — `signal_v1/` 표기 + `web-ai/` 표기 통일.

Plan passes self-review.
