# SPRINT-001 — 스켈레톤: XState FSM + orchestrator + CLI

> **목표**: 결정론적 파이프라인의 뼈대를 세운다. XState 머신이 메모리에서 돌고, SQLite 에 상태가 저장되고, `rails status` CLI 로 조회 가능해야 한다.

## Type
`scaffold`

## Prerequisites
- Sprint 000 완료
- Node 22, pnpm 설치됨
- `.plans/design/state-machine.md` 확정

## Scope

- `package.json` / `tsconfig.json` (strict + noUncheckedIndexedAccess)
- Core 디렉토리 구조: `src/orchestrator/`, `src/contract/`, `src/cli/`, `tests/`
- XState v5 머신 정의 (`src/orchestrator/machine.ts`)
- Zod 이벤트/컨텍스트 스키마 (`src/orchestrator/events.ts`)
- SQLite 스키마 + migration (`src/orchestrator/store.ts`)
- citty CLI 뼈대 (`rails <subcommand>`)
- `rails start` — 빈 파이프라인 시작
- `rails status` — 현재 상태 표시
- Vitest 테스트: 머신 상태 전이 단위 테스트 (성공 경로 1건 + 에러 경로 1건)

## Non-Goals

- 실제 자매 spawn (Sprint 004)
- Sprint Contract validator (Sprint 003)
- Skill enforcement hook 로직 (Sprint 002)
- 재시도 policy 실구현 (Sprint 005)
- QA runtime (Sprint 006)
- 디스코드 브릿지 (Sprint 004 또는 별도)

## Tasks

| # | 내용 | DoD | Depends | Status |
|---|---|---|---|---|
| 1.1 | `package.json` + `pnpm-lock.yaml` + 의존성 설치 | `pnpm install` 성공 | — | cc:TODO |
| 1.2 | `tsconfig.json` strict + noUncheckedIndexedAccess | `pnpm tsc --noEmit` 통과 | 1.1 | cc:TODO |
| 1.3 | 디렉토리 구조 생성 (`src/`, `tests/`, `fixtures/`) | `ls src/` 기대대로 | 1.1 | cc:TODO |
| 1.4 | `src/orchestrator/events.ts` — Zod 이벤트 스키마 | 타입체크 통과 | 1.2 | cc:TODO |
| 1.5 | `src/orchestrator/context.ts` — FSM context 타입 | 타입체크 통과 | 1.4 | cc:TODO |
| 1.6 | `src/orchestrator/machine.ts` — XState v5 머신 (stub actor) | `createActor` 성공 | 1.5 | cc:TODO |
| 1.7 | `src/orchestrator/store.ts` — better-sqlite3 + 스키마 + prepared statements | 테이블 4개 생성됨 | 1.1 | cc:TODO |
| 1.8 | `src/orchestrator/persist.ts` — FSM snapshot ↔ SQLite 변환 | snapshot round-trip 테스트 통과 | 1.6, 1.7 | cc:TODO |
| 1.9 | `src/cli/index.ts` — citty 진입점 | `pnpm rails --help` 출력 | 1.1 | cc:TODO |
| 1.10 | `src/cli/start.ts` — `rails start <projectName>` | 파이프라인 생성, ULID 반환 | 1.9, 1.8 | cc:TODO |
| 1.11 | `src/cli/status.ts` — `rails status [<id>]` | 현재 상태 표 출력 | 1.9, 1.8 | cc:TODO |
| 1.12 | `tests/machine.test.ts` — 성공 경로 + 에러 경로 | 2개 이상 pass | 1.6 | cc:TODO |
| 1.13 | `tests/store.test.ts` — snapshot round-trip | 1개 이상 pass | 1.8 | cc:TODO |
| 1.14 | `src/logger.ts` — pino 구조화 로거 + pipelineId 필드 | 로그 JSON 형식 확인 | 1.1 | cc:TODO |
| 1.15 | `src/env.ts` — Zod 검증 env | 환경변수 검증 실패 시 throw | 1.1 | cc:TODO |
| 1.16 | README 실행 방법 섹션 업데이트 | `## 실행 방법` 존재 | — | cc:TODO |

## Definition of Done

### 자동 검증 (contract validator)
- `pnpm install` exit 0
- `pnpm tsc --noEmit` exit 0
- `pnpm test` 전체 통과 (머신 + store 최소 3개)
- `pnpm rails --help` exit 0 + 출력에 `start`, `status` 포함
- `pnpm rails start test-project` → ULID 출력
- `pnpm rails status <id>` → `idle` 또는 `planning` 상태 표시
- SQLite 파일 (`data/rails.db`) 생성 확인
- `package.json` lockfile 이 `pnpm-lock.yaml` (yarn/npm 아님)

### 수동 검증 (다랑이 manual)
- [ ] 아무 파일에도 `console.*` 호출 없음 (pino 사용)
- [ ] 아무 파일에도 `any` 타입 없음 (Zod 경계 제외)
- [ ] 모든 외부 입력에 Zod 검증 존재
- [ ] 에러 처리에 Result / neverthrow 또는 명시적 try/catch + 재던지기
- [ ] `.claude/rules/stack.md` 의 코딩 룰 전수 준수

## 환경 전제

- `node --version` ≥ 22
- `pnpm --version` ≥ 9
- `/home/erang/hanarang-rails/` 쓰기 권한

## Risks

- XState v5 + TypeScript strict + Zod 조합이 typegen 세팅 초기 삽질 가능 → **완화**: fixture 예제 따라하기
- better-sqlite3 네이티브 빌드 — Node 22 ABI 대응 필요 → **완화**: `@types/better-sqlite3` + build-from-source 옵션
- FSM snapshot round-trip 테스트가 XState 내부 구현 의존 → **완화**: public API (`getPersistedSnapshot` / `restore`) 만 사용

## Exit Criteria

- 모든 태스크 `cc:완료`
- `pnpm test` 전부 pass
- Plans.md 에서 SPRINT-001 Status 가 `cc:완료 [hash]`
- feature 브랜치 머지됨 (PR + 다랑이 QA)