# stock-lab → stock 리네이밍 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:** `stock-lab` 컨테이너/디렉토리/환경변수를 `stock` 으로 graduation. lab 네이밍 정책 정리 + V2 Phase 1 작업 시작 전 선행.

**Architecture:** Atomic refactor — web-backend repo 안의 모든 stock-lab 참조를 한 commit으로 갱신 (git mv + docker-compose + agent-office + nginx + 문서). web-ui/workspace CLAUDE.md 별도 commit. 메모리는 controller 직접 갱신. Python `app.*` import 경로 + API URL `/api/stock/...` + DB 파일 그대로 유지.

**Tech Stack:** Git (mv with history), Docker Compose, nginx upstream, Python FastAPI / httpx.

**선행 spec**: `web-ui/docs/superpowers/specs/2026-05-15-stock-lab-rename-to-stock.md`

---

## 사전 가정

- web-backend repo 와 web-ui repo 는 별도 git 저장소
- `workspace/CLAUDE.md` 는 git 관리 외 파일 (단순 편집)
- `stock-lab/.venv/` 디렉토리는 `.gitignore` 되어 있음 (Windows 로컬 가상환경, 변경 영향 무관)
- Gitea webhook 자동 배포: web-backend push → deployer rsync + docker compose up

---

## 파일 변경 매트릭스 요약 (Task 별로 상세)

```
[Task 1] grep 사전 검토 (코드 변경 0)

[Task 2] web-backend atomic commit
  - git mv stock-lab → stock (수십 파일)
  - docker-compose.yml (서비스 키 + container_name + build.context + depends_on + agent-office env)
  - agent-office/app/config.py (STOCK_LAB_URL → STOCK_URL)
  - agent-office/app/service_proxy.py (import + 5 함수)
  - agent-office/app/agents/stock.py (있다면)
  - agent-office/tests/test_stock_screener_job.py
  - nginx/default.conf (upstream + proxy_pass)
  - CLAUDE.md, README.md, STATUS.md
  - scripts/deploy-nas.sh, deploy.sh

[Task 3] web-ui commit
  - web-ui/CLAUDE.md

[Task 4] workspace 편집 (git 없음 가능)
  - workspace/CLAUDE.md

[Task 5] 메모리 갱신 (controller, 별도 git 외)
  - project_workspace.md / project_scale.md / project_stock_screener.md / nas_infra.md
  - feedback_lab_naming.md (graduation 사례)

[Task 6] 배포 + 검증
  - 사용자 push (Gitea 자격증명) + NAS 검증
```

---

### Task 1: 사전 검토 — 모든 stock-lab 참조 위치 확인

**Files:** (검증만, 변경 없음)

- [ ] **Step 1: web-backend stock-lab 참조 전체 grep (docs / .venv / __pycache__ 제외)**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend
grep -rln "stock-lab\|STOCK_LAB" . \
  --exclude-dir=.venv --exclude-dir=__pycache__ --exclude-dir=.git --exclude-dir=docs \
  2>&1 | sort
```

Expected output (예상): 다음 파일들이 등장해야 함:
- `./agent-office/app/agents/stock.py`
- `./agent-office/app/config.py`
- `./agent-office/app/service_proxy.py`
- `./agent-office/tests/test_stock_screener_job.py`
- `./CLAUDE.md`
- `./docker-compose.yml`
- `./nginx/default.conf`
- `./README.md`
- `./scripts/deploy-nas.sh`
- `./scripts/deploy.sh`
- `./STATUS.md`
- `./stock-lab/...` (stock-lab 내부 파일들 — `app/main.py`, 테스트 등 내부 참조는 디렉토리 rename 으로 자연 해소)

- [ ] **Step 2: web-ui stock-lab 참조 grep**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ui
grep -rln "stock-lab" . \
  --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=docs \
  2>&1 | sort
```

Expected: `./CLAUDE.md` 만.

- [ ] **Step 3: nginx/default.conf 정확한 변경 라인 식별**

```bash
grep -nE "stock-lab|upstream stock" /c/Users/jaeoh/Desktop/workspace/web-backend/nginx/default.conf
```

Expected: `upstream stock-lab { ... }` 블록 정의 + `proxy_pass http://stock-lab` 호출 라인 (1-3 곳).

- [ ] **Step 4: web-backend stock-lab 내부의 자기 참조 확인 (디렉토리 rename 후 영향)**

```bash
grep -rln "stock-lab" /c/Users/jaeoh/Desktop/workspace/web-backend/stock-lab/ \
  --exclude-dir=.venv --exclude-dir=__pycache__ 2>&1 | sort
```

Expected: `app/main.py` 의 헬스체크 메시지 + 일부 CLAUDE.md/README.md 문구. Python `app.*` import 는 stock-lab 문자열 없으므로 0건. 발견된 매칭은 Task 2 의 7단계 (디렉토리 내부 문서) 에서 처리.

- [ ] **Step 5: 사용자에게 `.venv` 삭제 요청 (선택사항이지만 git mv 안전성 향상)**

사용자에게 다음 메시지:
> "git mv stock-lab → stock 직전에 `web-backend/stock-lab/.venv/` 디렉토리 삭제 권장 (Windows local 가상환경, .gitignore 되어있어 영향 없음. 사용 시 재생성 필요). 삭제 완료 후 Task 2 진행."

Step 5 는 사용자 직접 실행:
```bash
rm -rf /c/Users/jaeoh/Desktop/workspace/web-backend/stock-lab/.venv
```

- [ ] **Step 6: Step 1-4 결과 기록 (commit 없음, Task 2 의 cross-check 자료)**

기록할 항목:
- 변경 대상 파일 N개 (Step 1 출력)
- nginx config 의 정확한 변경 라인 (예: 라인 12, 18, 25 등)
- 사용자가 `.venv` 삭제 완료했는지

---

### Task 2: web-backend repo atomic commit

**Files:** (web-backend repo)
- Rename: `stock-lab/` → `stock/`
- Modify: `docker-compose.yml`
- Modify: `agent-office/app/config.py`
- Modify: `agent-office/app/service_proxy.py`
- Modify: `agent-office/app/agents/stock.py` (해당 시)
- Modify: `agent-office/tests/test_stock_screener_job.py`
- Modify: `nginx/default.conf`
- Modify: `CLAUDE.md`
- Modify: `README.md`
- Modify: `STATUS.md`
- Modify: `scripts/deploy-nas.sh`
- Modify: `scripts/deploy.sh`

- [ ] **Step 1: git mv 디렉토리 rename**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend
git mv stock-lab stock
git status --short | head -10
```

Expected: git status 에 `R  stock-lab/... -> stock/...` 라인 다수. .venv 가 사용자에 의해 사전 삭제되었다면 무관, 살아있어도 .gitignore 로 untracked.

- [ ] **Step 2: docker-compose.yml 갱신**

`docker-compose.yml` 안 4 곳 변경:
1. `services:` 아래 `stock-lab:` 키 → `stock:`
2. `container_name: stock-lab` → `container_name: stock`
3. `build:` 의 `context: ./stock-lab` → `context: ./stock`
4. `frontend:` 의 `depends_on:` 항목 중 `- stock-lab` → `- stock`
5. `agent-office:` 의 `environment:` 안 `STOCK_LAB_URL=http://stock-lab:8000` → `STOCK_URL=http://stock:8000`

수정 명령 (Edit tool 로 안전하게):
- `stock-lab:` 단일 occurrence → `stock:`
- `container_name: stock-lab` → `container_name: stock`
- `context: ./stock-lab` → `context: ./stock`
- `- stock-lab` (frontend.depends_on 항목) → `- stock`
- `STOCK_LAB_URL=http://stock-lab:8000` → `STOCK_URL=http://stock:8000`

- [ ] **Step 3: agent-office/app/config.py 갱신**

`STOCK_LAB_URL = os.getenv("STOCK_LAB_URL", "http://stock-lab:8000")` 형태의 라인을:
```python
STOCK_URL = os.getenv("STOCK_URL", "http://stock:8000")
```
으로 교체. 다른 lab URL (MUSIC_LAB_URL 등) 은 그대로 유지.

- [ ] **Step 4: agent-office/app/service_proxy.py 갱신**

상단 import:
```python
from .config import STOCK_LAB_URL, MUSIC_LAB_URL, BLOG_LAB_URL, REALESTATE_LAB_URL
```
을:
```python
from .config import STOCK_URL, MUSIC_LAB_URL, BLOG_LAB_URL, REALESTATE_LAB_URL
```
으로 변경.

함수 본문의 `STOCK_LAB_URL` 사용 5개 (fetch_stock_news / fetch_stock_indices / summarize_stock_news / refresh_screener_snapshot / run_stock_screener) 모두 `STOCK_URL` 로 변경. 또한 본 spec 이후 추가된 `refresh_ai_news_sentiment` 함수도 STOCK_URL 사용.

가장 단순한 방법: 파일 안 모든 `STOCK_LAB_URL` → `STOCK_URL` 치환 (replace_all).

- [ ] **Step 5: agent-office/app/agents/stock.py 갱신**

다음 패턴 grep:
```bash
grep -n "stock-lab\|STOCK_LAB" /c/Users/jaeoh/Desktop/workspace/web-backend/agent-office/app/agents/stock.py
```

매칭이 있으면 (`stock-lab` 호스트 URL 또는 환경변수명 직접 참조) 갱신. 없으면 skip.

- [ ] **Step 6: agent-office/tests/test_stock_screener_job.py 갱신**

```bash
grep -n "stock-lab\|STOCK_LAB" /c/Users/jaeoh/Desktop/workspace/web-backend/agent-office/tests/test_stock_screener_job.py
```

mock URL 또는 환경변수 참조 갱신. `STOCK_LAB_URL` → `STOCK_URL`, `http://stock-lab:` → `http://stock:`.

- [ ] **Step 7: nginx/default.conf 갱신**

Task 1 Step 3 에서 식별된 라인 모두 변경:
- `upstream stock-lab` → `upstream stock`
- `server stock-lab:8000;` → `server stock:8000;`
- `proxy_pass http://stock-lab` → `proxy_pass http://stock`

- [ ] **Step 8: 운영 문서 갱신 (CLAUDE.md / README.md / STATUS.md / scripts/)**

각 파일 grep 후 모든 stock-lab 언급을 stock 으로 교체:
- `web-backend/CLAUDE.md` — 디렉토리 표 + 서비스 표 + 환경변수 표
- `web-backend/README.md` — 동일
- `web-backend/STATUS.md` — 동일
- `web-backend/scripts/deploy-nas.sh` — stock-lab 호출/경로 갱신
- `web-backend/scripts/deploy.sh` — 동일

수정 방법: 각 파일에 대해 grep → Edit tool replace_all (단, 의도적 보존 항목 — 예: 과거 변경 이력 등 — 있는지 검토).

- [ ] **Step 9: stock 디렉토리 내부 문서 갱신**

Task 1 Step 4 에서 발견된 stock-lab 내부 자기 참조 (예: `stock/CLAUDE.md`, `stock/app/main.py` 헬스체크 문구) 모두 갱신.

- [ ] **Step 10: agent-office 테스트 회귀 검증**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend/agent-office
python -m pytest tests/test_stock_screener_job.py -v
```

Expected: PASS — `STOCK_LAB_URL` 참조 없이 새 `STOCK_URL` 환경변수 기반으로 mock 통과.

- [ ] **Step 11: stock pytest 회귀**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend/stock
python -m pytest --ignore=app/test_scraper.py -q 2>&1 | tail -5
```

Expected: 80+ tests passed (이전 76 + Phase 1 작업 전 검증). 디렉토리 이름만 변경, 코드 무변. 회귀 0건.

- [ ] **Step 12: 최종 grep 검증 — stock-lab 잔여 0건**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend
grep -rln "stock-lab\|STOCK_LAB" . \
  --exclude-dir=.venv --exclude-dir=__pycache__ --exclude-dir=.git --exclude-dir=docs \
  2>&1 | sort
```

Expected: **0 lines** (의도적 보존된 docs/ 제외).

만약 0건이 아니면 빠진 위치 찾아서 추가 갱신 후 재검증.

- [ ] **Step 13: web-backend atomic commit**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend
git add -A
git status --short | head -20
git commit -m "refactor: rename stock-lab → stock (graduation)

- git mv stock-lab/ → stock/
- docker-compose.yml: 서비스 키 + container_name + build.context +
  frontend.depends_on + agent-office STOCK_LAB_URL → STOCK_URL
- agent-office/app: config.py, service_proxy.py STOCK_LAB_URL → STOCK_URL
- nginx/default.conf: upstream + proxy_pass 갱신
- CLAUDE.md / README.md / STATUS.md / scripts/ 문구 갱신

lab 네이밍 정책 (feedback_lab_naming.md) 에 따라 정식 graduation.
API URL / Python import / DB 파일명은 변경 없음."
```

---

### Task 3: web-ui CLAUDE.md 갱신

**Files:**
- Modify: `web-ui/CLAUDE.md` (web-ui repo)

- [ ] **Step 1: stock-lab 언급 grep**

```bash
grep -n "stock-lab" /c/Users/jaeoh/Desktop/workspace/web-ui/CLAUDE.md
```

Expected: 디렉토리 경로 / 라우팅 설명 / API 표 등에서 다수 매칭.

- [ ] **Step 2: 모두 stock 으로 교체**

Edit tool 의 `replace_all=true` 로 `stock-lab` → `stock` 일괄 치환. 단, "stock screener" 같은 단어는 영향 없음 (정확한 `stock-lab` 문자열만 매칭).

- [ ] **Step 3: commit**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ui
git add CLAUDE.md
git commit -m "docs: rename stock-lab → stock in CLAUDE.md"
```

---

### Task 4: workspace/CLAUDE.md 갱신 (git 외 가능)

**Files:**
- Modify: `/c/Users/jaeoh/Desktop/workspace/CLAUDE.md`

- [ ] **Step 1: git 관리 여부 확인**

```bash
ls /c/Users/jaeoh/Desktop/workspace/.git 2>&1
```

Expected: `No such file or directory` — workspace 자체는 git repo 아님. 단순 파일 편집.

(만약 git 관리 중이라면 별도 commit 진행)

- [ ] **Step 2: stock-lab 언급 grep + 교체**

```bash
grep -n "stock-lab" /c/Users/jaeoh/Desktop/workspace/CLAUDE.md
```

Edit tool 로 `stock-lab` → `stock` 일괄 치환.

- [ ] **Step 3: 변경 사항 사용자에게 알림 (commit 없음, 단순 파일)**

workspace/CLAUDE.md 는 단순 파일 — 자동 syncing 없음. 사용자에게 다음 메시지 전달:
> "workspace/CLAUDE.md 갱신 완료. git 관리 외 파일이라 commit 없음. 다음 세션부터 자동 적용."

---

### Task 5: 메모리 갱신 (controller 직접)

**Files:**
- Modify: `C:\Users\jaeoh\.claude\projects\C--Users-jaeoh-Desktop-workspace-web-ui\memory\project_workspace.md`
- Modify: `...\memory\project_scale.md`
- Modify: `...\memory\project_stock_screener.md`
- Modify: `...\memory\nas_infra.md`
- Modify: `...\memory\feedback_lab_naming.md` (graduation 사례 추가)

- [ ] **Step 1: 메모리 폴더 grep**

```bash
grep -rln "stock-lab\|STOCK_LAB" /c/Users/jaeoh/.claude/projects/C--Users-jaeoh-Desktop-workspace-web-ui/memory/ 2>&1
```

매칭 파일 모두 확인.

- [ ] **Step 2: 각 메모리에서 stock-lab → stock 갱신**

다음 표를 보고 각 파일에서 Edit:

| 파일 | 주요 갱신 |
|------|----------|
| `project_workspace.md` | "stock-lab/" → "stock/" (디렉토리 경로) |
| `project_scale.md` | 백엔드 서비스 표의 stock-lab 행 → stock |
| `project_stock_screener.md` | 백엔드 위치 / 컨테이너 이름 모두 |
| `nas_infra.md` | Docker 서비스 포트 표 + nginx 라우팅 |

- [ ] **Step 3: feedback_lab_naming.md 에 graduation 사례 등재**

기존 메모리 본문 끝에 다음 추가:
```markdown

## Graduation 이력
- **2026-05-15**: `stock-lab` → `stock` graduation. 8 노드 screener + 캔버스 UI + AI 뉴스 Phase 1 + V2 시그널 파이프라인 중심 = 정식 서비스 단계. 디렉토리/컨테이너/환경변수 (`STOCK_LAB_URL` → `STOCK_URL`) 갱신. API URL `/api/stock/*` + Python import / DB 파일명 그대로.
```

- [ ] **Step 4: MEMORY.md 인덱스의 stock_screener 행에 영향 있나 확인**

```bash
grep -n "stock-lab" /c/Users/jaeoh/.claude/projects/C--Users-jaeoh-Desktop-workspace-web-ui/memory/MEMORY.md
```

매칭 있으면 갱신, 없으면 skip.

- [ ] **Step 5: 메모리 폴더 잔여 grep 검증 (0건)**

```bash
grep -rln "stock-lab\|STOCK_LAB" /c/Users/jaeoh/.claude/projects/C--Users-jaeoh-Desktop-workspace-web-ui/memory/ 2>&1
```

Expected: 0 lines (feedback_lab_naming.md의 graduation 본문 안에 의도적으로 "stock-lab" 언급은 가능 — 정책 사례 명시).

---

### Task 6: 배포 + 운영 검증

**Files:** (실행만, 변경 없음)

- [ ] **Step 1: web-backend push (사용자 수동, Gitea 자격증명 필요)**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-backend
git push origin main
```

자격증명 prompt 시 사용자가 입력. push 성공 시 Gitea webhook → deployer rsync + docker compose up 자동.

- [ ] **Step 2: web-ui push (사용자 수동)**

```bash
cd /c/Users/jaeoh/Desktop/workspace/web-ui
git push origin main
```

자격증명 prompt. 본 push 는 CLAUDE.md 한 줄 변경만이라 deployer 영향 없음.

- [ ] **Step 3: NAS 컨테이너 상태 확인 (사용자가 NAS SSH)**

```bash
docker ps --format "{{.Names}}: {{.Status}}" | grep -E "stock|agent-office"
```

Expected:
- `stock: Up (healthy)` 라인 존재 (옛 stock-lab 컨테이너는 사라짐)
- `agent-office: Up (healthy)`

- [ ] **Step 4: stock 컨테이너 로그 확인**

```bash
docker logs stock --tail 30
```

Expected: FastAPI startup 로그, init_db 완료, 어떤 stock-lab 잔여 참조나 에러 없음.

- [ ] **Step 5: agent-office 환경변수 확인**

```bash
docker exec agent-office env | grep -E "STOCK|stock"
```

Expected:
- `STOCK_URL=http://stock:8000` (새 변수)
- (옛 `STOCK_LAB_URL` 잔여가 없어야 — `.env` 파일에 남아있으면 사용자가 수동 삭제)

- [ ] **Step 6: API curl 검증**

```bash
curl -s https://gahusb.synology.me/api/stock/news | python -m json.tool | head -10
curl -s https://gahusb.synology.me/api/stock/screener/runs | python -m json.tool | head -10
```

Expected: 200 응답, JSON 파싱 정상.

- [ ] **Step 7: agent-office 수동 트리거 (테스트)**

```bash
curl -X POST "https://gahusb.synology.me/api/agent-office/command" \
  -H "Content-Type: application/json" \
  -d '{"agent":"stock","action":"run_ai_news"}'
```

Expected: `{"ok": true, "message": "AI 뉴스 분석 트리거 완료"}`. 30-60초 후 텔레그램 메시지 도착 = stock 호스트 라우팅 정상.

- [ ] **Step 8: web-ui 페이지 회귀 (브라우저)**

`https://gahusb.synology.me/stock/screener` 접속:
- 캔버스 모드 진입 정상
- 슬라이더 조작 → settings PUT 정상 (X-WebAI-Key 미사용 상태에서도 통과 — 인증은 Phase 1 작업)
- 노드 변경 즉시 반영

`https://gahusb.synology.me/portfolio` 접속:
- portfolio 페이지 정상 (current_price/PnL 표시 — Phase 1 작업 전이므로 raw 값만 표시)

- [ ] **Step 9: 운영 .env 파일 정리 안내 (사용자 수동)**

NAS의 `/volume1/docker/webpage/.env` 파일에서:
- `STOCK_LAB_URL=...` 라인 삭제 (또는 `STOCK_URL=...` 로 갱신)
- agent-office 컨테이너 재기동 필요 시: `docker restart agent-office`

사용자에게 알림:
> "NAS의 .env 파일에서 옛 STOCK_LAB_URL 라인 제거 권장. agent-office 의 default fallback (`http://stock:8000`) 으로 동작 가능하지만, 명시적 STOCK_URL 등재가 깔끔."

---

## 완료 후 검증 체크리스트

- [ ] `web-backend/stock-lab/` 사라지고 `stock/` 존재 (`ls web-backend/stock` 확인)
- [ ] `grep -rln "stock-lab\|STOCK_LAB" web-backend --exclude-dir=docs --exclude-dir=.venv --exclude-dir=__pycache__ --exclude-dir=.git` → 0 lines
- [ ] web-ui/CLAUDE.md stock-lab 0건
- [ ] workspace/CLAUDE.md stock-lab 0건
- [ ] 메모리 폴더 stock-lab 0건 (feedback_lab_naming.md graduation 본문 외)
- [ ] docker ps 에 `stock` 컨테이너 healthy
- [ ] curl `/api/stock/news` 200
- [ ] agent-office `run_ai_news` 수동 트리거 + 텔레그램 도착
- [ ] stock pytest 76+ tests passed (회귀 0)
- [ ] agent-office tests 통과
- [ ] web-ui 페이지 (portfolio + screener) 정상

## 본 plan 완료 후 다음 단계

- **Confidence Signal Pipeline V2 Phase 1 brainstorming 시작** (이전 발표 디자인 그대로, 새 이름 `stock` 기준)
- spec → plan → 실행 (1주 작업 예상)