docs: add github workflow templates and execution guides

.github/ISSUE_TEMPLATE/versioned-feature-issue.md

@@ -0,0 +1,25 @@
+---
+name: Versioned Feature Issue
+about: 버전과 기능 단위로 작업을 분해하는 이슈 템플릿
+title: "[v0.x.x] "
+labels: ["type:feature"]
+assignees: []
+---
+
+## 배경
+
+-
+
+## 범위
+
+- 
+
+## 완료 조건
+
+- [ ] 
+- [ ] 
+- [ ] 
+
+## 비고
+
+- 

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## 요약
+- 
+
+## 관련 이슈
+- Closes #
+
+## 변경 범위
+- 
+
+## 설계/제품 규칙 체크
+- [ ] look-ahead bias를 추가하지 않았다
+- [ ] production prompt self-modification을 추가하지 않았다
+- [ ] 모델 라우팅은 role 기준으로 configurable 하다
+- [ ] deterministic parsing/scoring 우선 원칙을 유지했다
+- [ ] LLM 호출은 explicit schema / structured output 기준을 따른다
+- [ ] prediction artifact 저장 필드가 필요한 경우 함께 반영되었다
+- [ ] UI가 uncertainty와 invalidation condition을 숨기지 않는다
+
+## 검증
+- [ ] `pytest services/api/tests -q`
+- [ ] `npx pnpm --filter @finance-helper/web exec tsc --noEmit`
+- [ ] 로컬에서 핵심 플로우를 직접 확인했다
+
+## 리스크 / 후속 작업
+- 

.gitignore

@@ -18,3 +18,4 @@ services/api/alembic/versions/__pycache__
 scripts/__pycache__
 .codex-*.log
 TT_Main/
+*.egg-info/

README.md

@@ -1 +1,133 @@
-# TT_Main
+# Finance Helper
+
+미국 공식 이벤트, 미국 시장 반응, 한국 시장의 과거 반응 패턴을 연결해 다음 영업일 한국 시장 테마와 주도주 후보를 예측하는 개인용 리서치 플랫폼입니다.
+
+## 핵심 목표
+
+- 공식 원문과 신뢰 가능한 시장 데이터만 우선 수집
+- 중복 제거와 이벤트 클러스터링을 통해 의미 있는 사건만 남김
+- 미국 지수/섹터 ETF/직접 관련주/크로스애셋 반응으로 이벤트를 검증
+- 한국 테마와 주도주/2등주를 명시적 규칙과 아날로그 검색으로 번역
+- 멀티 에이전트 논증과 판정 모델로 확신과 불확실성을 분리
+- 리플레이와 롤링 OOS 평가로 프롬프트/라우팅/가중치를 게이트 방식으로만 개선
+
+## 기술 스택
+
+- Web: Next.js App Router, TypeScript, Tailwind CSS
+- API / Workers: FastAPI, SQLAlchemy, arq, OpenAI Responses API
+- Data: PostgreSQL, Redis, TimescaleDB extension
+- Infra: Docker Compose
+- Testing: Vitest, Pytest
+
+## 빠른 시작
+
+### 1. 환경 준비
+
+```bash
+cp .env.example .env
+docker compose up -d db redis
+```
+
+### 2. Python 의존성 설치와 참조 데이터 시드
+
+```bash
+cd services/api
+python -m venv .venv
+.venv/Scripts/activate
+pip install -e .[dev]
+cd ../..
+python scripts/seed_reference_data.py
+```
+
+### 3. Node 의존성 설치
+
+```bash
+corepack enable
+pnpm install
+```
+
+### 4. 개발 서버 실행
+
+```bash
+pnpm dev
+```
+
+- Web: [http://localhost:3000](http://localhost:3000)
+- API: [http://localhost:8000/api/v1/health](http://localhost:8000/api/v1/health)
+
+### 5. 작업 큐 실행
+
+```bash
+pnpm --filter finance-helper-api worker
+```
+
+## 배치 작업
+
+- `POST /api/v1/jobs/ingest`: 공식 소스 RSS/피드 수집 작업 큐에 적재
+- `POST /api/v1/jobs/analyze`: 이벤트 정규화, 미국 반응 측정, 한국장 번역 작업 큐에 적재
+
+## 테스트
+
+```bash
+pnpm test
+```
+
+```bash
+cd services/api
+pytest
+ruff check app tests
+mypy app
+```
+
+## 주요 문서
+
+- [아키텍처 개요](docs/architecture.md)
+- [데이터베이스와 API 설계](docs/database-api.md)
+- [평가 방법론과 승격 게이트](docs/evaluation.md)
+- [UI 페이지 명세](docs/ui-spec.md)
+- [리스크와 한계](docs/risks.md)
+
+## 디렉터리 개요
+
+```text
+apps/web             Next.js 한국어 웹앱
+services/api         FastAPI API, 분석 엔진, 배치 워커
+packages/contracts   Web과 API 응답 계약 스키마
+infra/sql/init       DB 초기 SQL
+scripts              시드/운영 스크립트
+docs                 아키텍처와 운영 문서
+```
+
+## 현재 구현 범위
+
+- Phase 1: 모노레포, DB 모델, 시드, 대시보드/탐색기/테마/리플레이/평가/관리자 UI
+- Phase 2: 이벤트 분류, 점수화, 미국 반응 측정 엔진 기본 구현
+- Phase 3: 한국 테마 번역, 주도주/2등주 랭킹 기본 구현
+- Phase 4: OpenAI Responses API 기반 역할별 오케스트레이션 기본 구현
+- Phase 5: 평가 메트릭, 승격 판정 규칙, 리플레이 기본 응답 구현
+
+## 주의 사항
+
+- 실거래 주문 엔진은 포함하지 않습니다.
+- 프롬프트/라우팅/가중치는 자동 반영되지 않습니다.
+- 과거 재현 시 미래 정보 사용을 금지하는 구조를 유지해야 합니다.
+- 실제 운영 성능은 데이터 공급원 품질과 참조 매핑 정교도에 크게 의존합니다.
+## Run Shortcuts
+
+```bash
+pnpm dev
+```
+
+- Runs the web app and API together.
+
+```bash
+pnpm app:all
+```
+
+- Runs the web app, API, and worker together in one terminal.
+
+```bash
+pnpm dev:worker
+```
+
+- Runs only the background worker.

docs/github-issue-pr-plan-ko.md

@@ -0,0 +1,122 @@
+# GitHub Issue & PR Plan
+
+이 문서는 지금까지 사용자가 내린 주요 명령과 그에 따른 구현 흐름을 기능별, 버전별로 나눈 GitHub 작업 계획이다.
+
+## 명령 기준 분해
+
+1. `Please create a web project ... Start implementing the project files.`
+2. `Project rules ...`
+3. `Please design the project using DESIGN.md file.`
+4. `로컬에서 돌려볼라 하는데 명령어 뭐 입력해야돼`
+5. `그럼 버튼을 누르면 ... 작업이 실행되도록 수정해줄 수 있을까?`
+6. `작업 중 표시 / 최근 실행 결과 / 자동 새로고침`
+7. `수집 후 분석 실행` 오류 수정들
+8. `내일 한국장 예상 테마와 주도주 / 2등주 후보가 계속 중복`
+9. `과거 7일치 한국 증시 분석 ... 실제로 돌려서 채워넣어줘`
+10. `npx pnpm dev는 웹+API / npx pnpm app:all은 웹+API+워커`
+11. `AWS나 Oracle Cloud에 올리고 싶다`
+
+## 실제 생성할 Issue 목록
+
+### Issue A
+- 버전: `v0.1.0`
+- 제목: `[v0.1.0] 개인용 한미 이벤트 리서치 플랫폼 모노레포 스캐폴딩 구축`
+- 기준 명령:
+  - `Please create a web project ...`
+  - `Project rules ...`
+
+### Issue B
+- 버전: `v0.2.0`
+- 제목: `[v0.2.0] 미국 공식 소스 수집, 이벤트 정규화, 시장 반응 엔진 구현`
+- 기준 명령:
+  - `Please create a web project ...`
+
+### Issue C
+- 버전: `v0.3.0`
+- 제목: `[v0.3.0] 한국 테마 번역, 주도주/2등주 랭킹, 대시보드 기본 UI 연결`
+- 기준 명령:
+  - `Please create a web project ...`
+
+### Issue D
+- 버전: `v0.4.0`
+- 제목: `[v0.4.0] DESIGN.md 기반 전체 UI 리디자인과 공통 스타일 시스템 정리`
+- 기준 명령:
+  - `Please design the project using DESIGN.md file.`
+  - `변경된 DESIGN.md로 재 디자인해줘`
+  - `전체 페이지 전부 동일하게 다듬어줘`
+
+### Issue E
+- 버전: `v0.4.0`
+- 제목: `[v0.4.0] 웹 버튼 기반 파이프라인 실행, 작업 상태 표시, 자동 새로고침 추가`
+- 기준 명령:
+  - `그럼 버튼을 누르면 ...`
+  - `작업 중 표시 ...`
+  - `최근 실행 결과 ... 최대 최근 두 개`
+
+### Issue F
+- 버전: `v0.4.1`
+- 제목: `[v0.4.1] 수집/분석 파이프라인 런타임 오류 복구와 안정성 하드닝`
+- 기준 명령:
+  - Treasury 404 오류
+  - `float() argument must be a string or a real number, not 'Series'`
+  - 버튼/작업 상태 관련 반복 검증
+
+### Issue G
+- 버전: `v0.4.2`
+- 제목: `[v0.4.2] 한국장 예상 테마와 종목 후보 중복 제거 로직 개선`
+- 기준 명령:
+  - `내일 한국장 예상 테마와 주도주 / 2등주 후보가 계속 중복`
+
+### Issue H
+- 버전: `v0.5.0`
+- 제목: `[v0.5.0] 최근 7거래일 리플레이와 실제 한국장 반응 비교 페이지 구현`
+- 기준 명령:
+  - `현재 추론 과정을 통한 ... 일주일치의 과거 자료`
+  - `의미 없는 더미 데이터가 아니라 ... 실제로 돌려서 채워넣어줘`
+
+### Issue I
+- 버전: `v0.5.1`
+- 제목: `[v0.5.1] 예측 아티팩트 감사 추적과 프롬프트/모델 게이팅 평가 보강`
+- 기준 명령:
+  - `Project rules ...`
+  - 리플레이/평가 관련 후속 요구
+
+### Issue J
+- 버전: `v0.6.0`
+- 제목: `[v0.6.0] 로컬 실행 단순화와 클라우드 배포 준비 문서 정리`
+- 기준 명령:
+  - `로컬에서 돌려볼라 하는데 명령어 뭐 입력해야돼`
+  - `지금 명령어 입력하는게 너무 귀찮은데`
+  - `AWS나 Oracle ...`
+
+## PR 초안 분리안
+
+### PR 1
+- 제목: `feat: bootstrap monorepo and core platform contracts`
+- 브랜치: `codex/v0.1-bootstrap-platform`
+- 닫는 이슈: `A`
+
+### PR 2
+- 제목: `feat: add us ingestion pipeline and reaction engine`
+- 브랜치: `codex/v0.2-ingestion-reaction`
+- 닫는 이슈: `B`
+
+### PR 3
+- 제목: `feat: add korea translation engine and dashboard experience`
+- 브랜치: `codex/v0.3-korea-dashboard`
+- 닫는 이슈: `C`, `D`
+
+### PR 4
+- 제목: `feat: add job controls and harden pipeline reliability`
+- 브랜치: `codex/v0.4-pipeline-ops`
+- 닫는 이슈: `E`, `F`, `G`, `J`
+
+### PR 5
+- 제목: `feat: add weekly replay and evaluation audit trail`
+- 브랜치: `codex/v0.5-replay-eval`
+- 닫는 이슈: `H`, `I`
+
+## 메모
+
+- 현재 작업물은 하나의 큰 변경 세트로 누적되어 있어, 실제 PR 생성 전에는 브랜치 분리와 커밋 재구성이 필요하다.
+- 따라서 이슈는 지금 바로 GitHub에 생성하고, PR은 위 분리안을 기준으로 후속 정리하는 편이 가장 안전하다.