[태그:] Claude Code

# TrainsOut — 열차 탈출

## Status
**v1.2.0** — 한국 애플 앱스토어 출시 완료, 운영 중.
프로덕션 안정성이 최우선. **출시 빌드에 영향 줄 수 있는 변경은 반드시 사용자 확인.**

| 항목 | 내용 |
|---|---|
| 앱 이름 | 열차 탈출 - 퍼즐 게임 |
| 패키지명 | `com.hol4b.trainescapepuzzle` |
| 타겟 | iOS 전용 (한국 앱스토어). `android/` 폴더는 stale, 무시 |
| 카테고리 | 퍼즐 (4+) |
| 수익화 | AdMob only (배너 + 전면광고 + 리워드 광고) |
| 빌드 | **로컬 EAS 빌드만** (`eas build --local`). 클라우드 빌드 과금 금지 |

## Stack
- React Native + **Expo SDK 55** + TypeScript
- **Zustand** (`gameStore`, `devStore`)
- **Reanimated v4** (worklet 기반 애니메이션)
- **expo-audio** (BGM + SFX)
- **Expo Router** (파일 기반 라우팅)
- **react-native-google-mobile-ads 16.3.1** (서비스 추상화로 mock 폴백 지원)
- AsyncStorage (레벨 진행 저장)

## Directory
```
app/              Expo Router (index, levels, game/[level], settings)
components/       Grid, Train, Track, HUD, DevPanel, TutorialOverlay
store/            gameStore.ts, devStore.ts
engine/           collisionDetect.ts
hooks/            useSound, useInterstitialAd, useRewardedAd
services/         ad/ + sound/ (real + mock 이중 구현)
data/             generated.ts (200 레벨, gridSize 10×10 ~ 24×24)
assets/sounds/    BGM, move, collision, win, fail, bomb_explode
utils/i18n.ts     한국어 문자열
docs/SPEC.md      2026-03-27 원본 기획 스냅샷 (⚠️ 현재 코드와 다름, 참고용)
demo/             Shorts 녹화용 씬 코드 (프로덕션 빌드 제외) — 아직 없음, 도입 예정
shorts/           Shorts 녹화 툴링 (Node 스크립트) — 아직 없음, 도입 예정
```

## Data Model
```typescript
type Direction = 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
type TrainState = 'IDLE' | 'MOVING' | 'ESCAPED';
type TrainColor = 'RED' | 'BLUE' | 'GREEN' | 'YELLOW' | 'PURPLE' | 'ORANGE' | 'CYAN';

interface Train {
  id: string;
  row: number;
  col: number;
  direction: Direction;
  color: TrainColor;
  state: TrainState;
  length: number;          // 열차 칸 수
  offsets?: [number,number][]; // L/S/U형 모양 오프셋 (직선 열차면 undefined)
}

interface Level {
  id: number;
  gridSize: number;   // 실제 10~24
  trains: Train[];
  par?: number;       // 3-star 기준 이동수
  timeLimit?: number; // 일부 레벨 제한 시간
}
```

## 게임 메커닉 (v1.2.0 실제)
- **탭으로 열차 이동**: 방향대로 셀 단위로 이동, 경계 이탈 시 `ESCAPED`, 전체 탈출 시 `WIN`
- **충돌 감지**: 경로상 다른 열차 있으면 충돌 → 하트 -1, 원위치 복귀
- **하트**: 게임당 3개. `hearts === 0` 시 `FAIL`
- **폭탄**: Level 11+ 등장. 카운트다운, 시간 내 탈출 못 하면 폭발 (하트 감소)
- **타이머**: 일부 레벨에 제한 시간
- **별점**: `moves ≤ par → ⭐⭐⭐`, `≤ par+2 → ⭐⭐`, 이상 → `⭐`
- **튜토리얼 오버레이**: Level 1 (기본 조작), Level 11 (폭탄 설명)
- **드래그+줌**: 큰 그리드는 핀치 줌 + 팬, 작은 그리드는 화면에 맞춤 (`Grid.tsx`)
- **DevPanel**: 홈 로고 5연타 → `unlockAll`, 시간 조작 등 개발자 토글

## 수익화 (실제, SPEC 과 다름)
- **Banner**: 게임 화면 하단 (`SafeBannerAd` + `ErrorBoundary` 로 네이티브 모듈 누락 시 안전 fallback). Unit ID: `ca-app-pub-XXXXXXXXXX/XXXXXXXXXX`
- **Interstitial**: **5레벨 클리어마다** (`useInterstitialAd`). SPEC 의 "hearts=0 자동 광고" 와 다름
- **Rewarded**: 실패 오버레이의 **"광고 보고 하트 2개 복구"** 선택 버튼 (`useRewardedAd`). 강제 아님, 사용자 선택
- **SIMULATOR=1** env: AdMob 플러그인 자체 로드 안 함 (`app.config.js`). 시뮬레이터 개발/녹화 모드
- **Service abstraction** (`services/ad/`): 네이티브 모듈 없을 때 자동으로 mock 으로 폴백

## 애니메이션 타이밍
- 이동: 200ms (`Easing.out(Easing.quad)`)
- 탈출: 85ms/칸 linear
- 폭탄 긴급 펄스: 250ms 반복 (countdown ≤ 3)
- **`Date.now()` 등 비결정 시간 호출 없음** → 녹화 재현성 OK

---

## Shorts 파이프라인 (2026-04-12 도입, WIP)

마케팅용 YouTube Shorts 자동 제작 파이프라인. 주제 문장 → Claude Code 가 씬 코드 작성 → iOS 시뮬레이터 녹화 (`xcrun simctl io booted recordVideo`) → ffmpeg 후처리 → `out/<slug>.mp4`.

### 격리 원칙 (프로덕션 0 영향)
- 모든 Shorts 관련 코드는 **`/demo` 와 `/shorts`** 에만 존재
- 프로덕션 코드 (`app/`, `components/`, `store/`, `engine/`, `hooks/`, `services/`) 는 **`/demo` 를 절대 import 하지 않음**
- `.easignore` 가 `/demo`, `/shorts` 를 빌드 산출물에서 제외 (도입 시)
- 프로덕션 파일에 남는 유일한 수정은 **`testID` 프롭 추가** 뿐이며, 이는 런타임 영향 0 (메타데이터)

### testID 규칙 — **절대 제거하지 말 것**
Shorts 녹화의 `TapEmulator` 가 자동으로 탭할 엘리먼트를 찾기 위한 메타데이터입니다. 향후 E2E 테스트에도 재활용됩니다.

| 파일 | testID | 대상 |
|---|---|---|
| `components/Train.tsx` | `train-${id}` | 모든 열차 TouchableOpacity (L자형 `CellAnimated`, 직선 `StraightTrainAnimated` 양쪽) |
| `app/index.tsx` | `btn-logo` | 로고 탭 영역 (DevPanel 잠금 해제용) |
| `app/index.tsx` | `btn-start` | 시작하기/계속하기 버튼 |
| `app/index.tsx` | `btn-levels` | 레벨 선택 버튼 |
| `app/game/[level].tsx` | `btn-back` | 홈으로 돌아가기 |
| `app/game/[level].tsx` | `btn-next` | WIN 오버레이 다음 레벨 |
| `app/game/[level].tsx` | `btn-retry` | WIN 오버레이 다시 도전 |
| `app/game/[level].tsx` | `btn-watch-ad` | FAIL 오버레이 광고 시청 |
| `app/game/[level].tsx` | `btn-restart-one` | FAIL 오버레이 1레벨부터 다시 |

`testID` 는 React Native 에서 렌더·이벤트에 영향을 주지 않는 순수 메타데이터입니다. 번들 사이즈는 바이트 수준 증가, 런타임 비용 0.

### 디렉토리 (도입 시)
- **`/demo/`** — 앱 내 데모 모드
  - `entry.tsx` — `SHORTS_MODE=1` 전용 루트
  - `runtime/SceneHost.tsx`, `defineScene.ts`, `TapEmulator.tsx`, `Subtitles.tsx`, `signals.ts`
  - `scenes/*.tsx` — 씬 파일 (수동 또는 LLM 생성)
- **`/shorts/`** — 호스트 머신 Node 스크립트
  - `core/` — schema, postprocess (ffmpeg), cli, LLM 프롬프트
  - `adapter-expo/` — boot, launch, record (simctl)
  - `out/` — 완성된 mp4
  - `.cache/` — raw 녹화 중간 파일

### 연출 자유도
마케팅 목적이라 **"가상 레벨" 구성 허용**. 실제 Level 1 은 10×10 이지만, 임팩트를 위해 3×3 씬을 씬 파일 내에서 임의 구성 가능. **게임 룰/방식은 유지**.

### BGM 및 자막
- BGM 은 `assets/sounds/bgm.mp3` 등 앱 자체 트랙을 ffmpeg 후처리 단계에서 믹싱 (시뮬레이터 오디오는 녹화에 안 잡힘)
- 자막은 ffmpeg `drawtext` 번인 기본, 특수 연출 시 앱 내 오버레이

### 해상도
- 1080×1920 (9:16), iPhone 15 Pro 시뮬레이터 기준 크롭
- 노치 포함, 홈 인디케이터 크롭

---

## gstack

Use /browse skill from gstack for all web browsing.
Never use mcp__claude-in-chrome__* tools.

Available skills:
/office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
/design-consultation, /design-shotgun, /review, /ship, /land-and-deploy,
/canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only,
/design-review, /setup-browser-cookies, /setup-deploy, /retro,
/investigate, /document-release, /codex, /cso, /autoplan,
/careful, /freeze, /guard, /unfreeze, /gstack-upgrade

If skills not working: `cd .claude/skills/gstack && ./setup`

### Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
The skill has specialized workflows that produce better results than ad-hoc answers.

Key routing rules:
- Product ideas, "is this worth building", brainstorming → invoke office-hours
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
- Ship, deploy, push, create PR → invoke ship
- QA, test the site, find bugs → invoke qa
- Code review, check my diff → invoke review
- Update docs after shipping → invoke document-release
- Weekly retro → invoke retro
- Design system, brand → invoke design-consultation
- Visual audit, design polish → invoke design-review
- Architecture review → invoke plan-eng-review

# 열차 탈출 – Claude Code Project Spec

## Project Overview
선로 위 열차들을 충돌 없이 전부 탈출시키는 순서 퍼즐 게임.
React Native + Expo, iOS 개발.
**타겟: 한국 애플 앱스토어**

---

## 앱 기본 정보

| 항목 | 내용 |
|------|------|
| 앱 이름 | 열차 탈출 |
| 패키지명 | com.hol4b.trainescapepuzzle |
| 카테고리 | 퍼즐 |
| 연령 등급 | 전체 이용가 |
| 출시 스토어 | 애플 앱스토어 (한국) |
| 언어 | 한국어 |

---

## Tech Stack

| Layer | Choice | Reason |
|-------|--------|--------|
| Framework | React Native + Expo (SDK 51+) | 빠른 빌드, 단일 코드베이스 |
| Language | TypeScript | 타입 안전성 |
| State | Zustand | 경량 게임 상태 관리 |
| Animation | React Native Reanimated v3 | 60fps 열차 이동 |
| Ads | react-native-google-mobile-ads | AdMob 배너 + 전면광고 |
| Storage | AsyncStorage | 레벨 진행 저장 |
| Navigation | Expo Router | 파일 기반 라우팅 |

---

## Directory Structure

```
/app
  index.tsx              # 홈 화면
  game/[level].tsx       # 게임 플레이 화면
  levels.tsx             # 레벨 선택
  settings.tsx           # 설정 (사운드)
/components
  Grid.tsx               # 선로 그리드
  Train.tsx              # 열차 컴포넌트 (SVG + 애니메이션)
  Track.tsx              # 선로 배경 셀
  HUD.tsx                # 하트, 레벨, 이동수
  BannerAd.tsx           # 하단 배너 광고
  CrashEffect.tsx        # 충돌 이펙트
  InterstitialGate.tsx   # 생명 0 → 전면광고 게이트
/store
  gameStore.ts           # Zustand 게임 상태
/engine
  levelValidator.ts      # 레벨 풀이 검증 (BFS)
  collisionDetect.ts     # 충돌 감지
  levelGenerator.ts      # 레벨 데이터 파싱
/data
  levels/
    easy.ts              # 레벨 1-50 (3x3~4x4)
    medium.ts            # 레벨 51-150 (4x4~5x5)
    hard.ts              # 레벨 151-300 (5x5~6x6)
/assets
  sounds/
    train_move.mp3
    train_horn.mp3
    crash.mp3
/hooks
  useGameLoop.ts
  useSound.ts
  useAd.ts               # 광고 로드/표시 훅
```

---

## Core Game Engine Spec

### 테마 매핑

| Arrow Out 원작 | 열차 탈출 |
|---------------|-----------|
| 화살표 | 열차 (색상으로 구분) |
| 이동 방향 | 열차 진행 방향 |
| 그리드 셀 | 선로 교차점 |
| 충돌 | 열차 충돌 사고 |
| 화면 밖 이탈 | 역 도착 / 탈출 성공 |
| 하트 | 생명 (게임당 3개) |

### Data Model

```typescript
type Direction = 'UP' | 'DOWN' | 'LEFT' | 'RIGHT';
type TrainState = 'IDLE' | 'MOVING' | 'ESCAPED';
type TrainColor = 'RED' | 'BLUE' | 'GREEN' | 'YELLOW' | 'PURPLE';

interface Train {
  id: string;
  row: number;
  col: number;
  direction: Direction;
  color: TrainColor;
  state: TrainState;
}

interface Level {
  id: number;
  gridSize: number;  // 3~6
  trains: Train[];
  par?: number;      // 3-star 기준 이동수
}

interface GameState {
  level: Level;
  trains: Train[];
  hearts: number;    // 게임 시작 시 3, 충돌 시 -1
  moves: number;
  status: 'PLAYING' | 'WIN' | 'FAIL';
}
```

### 게임 루프

```
게임 시작
  → hearts = 3

train[id] 탭
  → state = MOVING
  → 셀 단위 이동, 각 셀 진입 시 충돌 체크
      충돌 감지:
        hearts -= 1
        CrashEffect 재생 (flash + haptics + 충돌음)
        state = IDLE (원위치 복귀)
        hearts === 0 → status = FAIL
      정상:
        계속 이동
  → 경계 이탈 → state = ESCAPED
  → 전체 ESCAPED → status = WIN

status === FAIL
  → InterstitialGate 발동
  → 전면광고 노출 (AdMob Interstitial)
  → 광고 종료 후 → hearts = 3, 현재 레벨 재시작
```

### 충돌 감지 규칙
- 셀 기반 이동 (픽셀 단위 아님)
- 이동 경로 전체 셀에 다른 열차 존재 여부 사전 체크
- 순차 탭만 허용 (동시 이동 불가)

---

## Level Data Format

```typescript
export const easyLevels: Level[] = [
  {
    id: 1,
    gridSize: 3,
    trains: [
      { id: 't1', row: 1, col: 0, direction: 'LEFT',  color: 'RED',   state: 'IDLE' },
      { id: 't2', row: 0, col: 1, direction: 'UP',    color: 'BLUE',  state: 'IDLE' },
      { id: 't3', row: 1, col: 2, direction: 'RIGHT', color: 'GREEN', state: 'IDLE' },
    ],
    par: 3,
  },
]
```

---

## Monetization: AdMob Only

```
광고 구성:
├── 배너 광고 (BannerAd)
│     위치: 게임 화면 하단 상시 노출
│     사이즈: BANNER (320x50)
│
└── 전면광고 (Interstitial)
      트리거: 생명 3개 모두 소진 (hearts === 0)
      플로우: FAIL 판정 → 광고 노출 → 광고 종료 → 생명 3개 복구 → 레벨 재시작
      주의: 광고 로드 실패 시에도 생명 복구 후 재시작 (광고 강제 X)

인앱결제: 없음
부스터: 없음
```

### useAd.ts 구현 가이드

```typescript
// hooks/useAd.ts
import { useInterstitialAd, TestIds } from 'react-native-google-mobile-ads';

const AD_UNIT_ID = __DEV__
  ? TestIds.INTERSTITIAL
  : 'ca-app-pub-XXXXXX/XXXXXX'; // 실제 AdMob Unit ID

export function useAd() {
  const { isLoaded, isClosed, load, show, error } = useInterstitialAd(AD_UNIT_ID);

  // 광고 사전 로드 (게임 시작 시 호출)
  const preload = () => load();

  // 생명 0 시 호출
  const showOnFail = async (onComplete: () => void) => {
    if (isLoaded) {
      show();
      // isClosed 감지 후 onComplete 호출
    } else {
      // 광고 없으면 바로 복구
      onComplete();
    }
  };

  return { preload, showOnFail, isLoaded };
}
```

### InterstitialGate 플로우

```
hearts === 0 발생
  → gameStore: status = 'FAIL'
  → InterstitialGate 컴포넌트 마운트
  → 광고 로드 완료 여부 확인
      완료: 전면광고 표시
      미완료: 스피너 0.5초 → 바로 복구
  → 광고 닫힘 이벤트 수신
  → gameStore: hearts = 3, status = 'PLAYING', 레벨 초기화
```

---

## UI/UX Spec

### 색상 팔레트 (다크 테마)
```
Background:  #0f1923
Grid/Track:  #1a2a3a
Track Line:  #2d4a6e
Train RED:   #e63946
Train BLUE:  #457b9d
Train GREEN: #2a9d8f
Train YELLOW:#f4a261
Train PURPLE:#9b72cf
Heart full:  #e63946
Heart empty: #2d3748
Text:        #f0f4f8
```

### 화면 구성
1. 홈: 로고, 시작하기, 레벨 선택, 설정
2. 레벨 선택: 그리드, 별점, 잠금
3. 게임: 선로 그리드 중앙, 상단 HUD (하트/레벨/이동수), 하단 배너광고
4. 클리어: "탈출 성공! 🚂" + 별점 + 다음/재도전
5. 실패 (hearts=0): InterstitialGate → 광고 → 자동 재시작

### HUD 하트 표시
```
hearts = 3 → ❤️❤️❤️
hearts = 2 → ❤️❤️🖤
hearts = 1 → ❤️🖤🖤
hearts = 0 → 🖤🖤🖤 → InterstitialGate 발동
```

### 애니메이션
- 이동: 200ms linear
- 충돌: red flash + Haptics.impactAsync(Heavy) + 충돌음 + 하트 -1 애니메이션
- 탈출: 화면 밖 슬라이드 아웃
- 클리어: 별 3개 드롭 + 경적음

---

## Development Phases

### Phase 1 – Core Engine (1주)
- [ ] `npx create-expo-app TrainEscape --template expo-template-blank-typescript`
- [ ] 의존성: zustand, react-native-reanimated@3, expo-router, expo-haptics, expo-av
- [ ] Grid + Track 컴포넌트 (SVG 선로)
- [ ] Train 컴포넌트 SVG 직접 구현
- [ ] 충돌 감지 엔진
- [ ] Zustand 상태 관리 (hearts 포함)
- [ ] 레벨 10개 동작 검증

### Phase 2 – Game Loop & UX (1주)
- [ ] 하트 시스템 (3개, 충돌 시 -1)
- [ ] hearts === 0 → FAIL 판정
- [ ] WIN/FAIL 화면 전환
- [ ] 별점 시스템 (par 기반)
- [ ] 레벨 선택 화면
- [ ] AsyncStorage 진행 저장
- [ ] 레벨 50개

### Phase 3 – AdMob 연동 (2일)
- [ ] react-native-google-mobile-ads 설치 및 설정
- [ ] BannerAd 컴포넌트 (게임 화면 하단)
- [ ] useAd 훅 구현
- [ ] InterstitialGate 컴포넌트 구현
- [ ] 테스트 광고 ID로 동작 검증
- [ ] 실제 AdMob Unit ID 교체

### Phase 4 – Polish & Submit (3일)
- [ ] 효과음 (expo-av)
- [ ] 햅틱 피드백
- [ ] Daily Challenge (오늘의 퍼즐)
- [ ] 앱 아이콘 + 스플래시
- [ ] 개인정보처리방침 페이지 (blog.hol4b.com에 게시)
- [ ] 한국 앱스토어 메타데이터 작성
- [ ] TestFlight 베타 테스트 → 앱스토어 심사 제출

---

## 한국 앱스토어 메타데이터

- 이름: `열차 탈출 - 퍼즐 게임`
- 부제: `선로를 탈출하라`
- 키워드: `퍼즐,뇌훈련,열차,탈출,두뇌,논리,기차,퍼즐게임,두뇌게임,브레인`
- 연령: 4+
- 개인정보처리방침 URL: 필수 (AdMob 사용으로 인해 심사 필수 항목)

---

## Known Risks & Mitigations

| 리스크 | 대응 |
|--------|------|
| 전면광고 UX 거부감 | hearts=0 일 때만 노출 → 빈도 낮아 수용 가능 |
| 광고 로드 실패 | 실패 시에도 생명 복구 후 재시작 (강제 광고 X) |
| Reanimated 성능 | worklet 기반 애니메이션 |
| 레벨 제작 시간 | 50개 수동 → BFS 자동 생성기 |
| 심사 거절 | 개인정보처리방침 URL 사전 준비 (AdMob 사용 시 필수) |

---

## Claude Code 첫 프롬프트

```
CLAUDE.md를 읽고 Phase 1부터 시작해줘.

1. Expo + TypeScript 프로젝트 초기화
2. 의존성 설치 (zustand, reanimated@3, expo-router, expo-haptics, expo-av)
3. 3x3 그리드에 열차 3개 렌더링
4. 열차는 React Native SVG로 직접 구현 (이미지 에셋 없이)
5. 탭 → 방향으로 이동 → 경계 이탈 시 ESCAPED 기본 동작 확인까지
```

# Decisions Register

<!-- Append-only. Never edit or remove existing rows.
     To reverse a decision, add a new row that supersedes it.
     Read this file at the start of any planning or research phase. -->

| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |
|---|------|-------|----------|--------|-----------|------------|---------|
| D001 | M001 | integration | AdMob milestone placement | Keep AdMob integration out of M001 and schedule it for a later milestone that assumes a development/native build path | Current library guidance confirms AdMob flows are not an Expo Go-first path, so mixing monetization into the first milestone would dilute proof of the core puzzle loop and add native build complexity too early. | No | collaborative |
| D002 | M001 | architecture | M001 sequencing focus | Plan M001 around proving puzzle feel and readability before broader game-shell or monetization work | The user emphasized that the first playable must not feel sluggish or frustrating, so early slices should be player-visible vertical increments that prove responsiveness, clarity, and fun rather than invisible technical layers. | Yes — if later testing shows shell or UX framing must move earlier | collaborative |
| D003 | M001/S01 | requirement | R001 | validated | S01 delivered a real home→level-1→tap-to-move→escape loop with deterministic store transitions, SVG board rendering, and passing movement/store tests plus successful Expo Metro boot proof. | Yes | agent |
| D004 | M001/S01 | requirement | R003 | validated | S01 established immediate tap responsiveness for the first playable loop by wiring direct train press handling to deterministic movement/store updates, exposing visible status/move labels, and proving the runtime boots cleanly in Expo with green automated tests. | Yes | agent |
| D005 | M001/S02/T02 | observability | How movement results are retained in the game store | Persist the full engine MovementResolution as `lastResolution` alongside the compact `lastInteraction` feedback snapshot. | This keeps the pure engine as the single source of truth while giving downstream UI and debugging surfaces direct access to path and collision metadata without recomputation or duplicated derivation logic. | Yes | agent |
| D006 | M001/S02 | requirement | R002 | validated | S02 delivered deterministic cell-based collision/movement contracts in the pure engine, persisted structured movement resolutions and last-interaction feedback in Zustand, exposed blocked/escaped/no-op outcomes in the game UI, and re-verified the behavior with 15 passing movement/store tests plus Expo Metro startup evidence. | Yes | agent |
| D007 | M001/S03 | requirement | R004 | validated | S03 added pure board-presentation derivation, visible exit markers, directional train visuals, highlighted attempted/blocked paths, collision-cell overlays, board legend and feedback cards, then proved the contract with passing boardPresentation + movement Jest suites and clean non-interactive Expo Metro startup on pinned port 8081. | Yes | agent |
| D008 | M001/S04 | requirement | R005 | validated | S04 expanded the easy pack into multiple handcrafted solvable levels, wired the pack into the home and game flows with deterministic replay/next-level behavior and malformed-param fallback, and verified it with passing Jest suites plus successful Expo Metro startup proof. | Yes | agent |
| D009 | M001/S05 | requirement | R005 | validated | S05 locked the multi-level easy-pack flow with integrated regression coverage for home entry, malformed fallback, replay reset, next-level progression, completed-pack behavior, and verified Expo Metro startup on the pinned 8081 path. | Yes | agent |
| D010 | M002 | pattern | 레벨 해금 방식 | 순차 해금 — 이전 레벨 클리어해야 다음 레벨 열림 | 선형 진행이 퍼즐 난이도 곡선 관리에 유리하고, 구현이 단순함 | Yes | collaborative |
| D011 | M002/S01 | requirement | R006 | validated | S01 added hearts to the shared game snapshot, surfaced explicit PLAYING/FAIL copy plus a fail CTA on the game screen, locked board input while FAIL, and verified the behavior with passing heart-system, integrated-flow, movement, and screen-level Jest suites plus clean TypeScript checks. | Yes | agent |
| D012 | M002/S02 | requirement | R007 | validated | S02 added deterministic WIN-only par-based star summaries, rendered the result card with replay/next-level or pack-complete branching, and proved the behavior with passing starRating, integratedPlayFlow, and gameScreenFailLoopScreen Jest suites. | Yes | agent |
| D013 | M002/S03 | requirement | R008 | active | S03 delivered the AsyncStorage-backed progress contract, home/levels/game route integration, and passing progression/levels-screen coverage, but the slice-level verification contract is not fully complete because gameScreenFailLoopScreen.test.tsx remains failing and the planned chained typecheck did not run. Requirement evidence advanced substantially, but full validation proof is not yet closed. | Yes | agent |
| D014 | M002/S04 | requirement | R005 | validated | S04 expanded the easy content pack from 6 to 50 ordered levels, preserved deterministic anchor fixtures, updated progression/UI regressions for first/middle/last and late-pack behavior, and re-verified the 50-level contract with passing levelPack, integratedPlayFlow, levelsScreen, progressPersistence, and TypeScript checks. | Yes | agent |
| D015 | M002/S05 | requirement | R005 | validated | S05 closed the remaining M002 proof gap by passing the mounted game-screen regression harness, the focused integrated progression/persistence/result/fail regression set, and TypeScript checks against the current 50-level easy pack. This now proves the real home→levels→play→FAIL→restart→WIN→next-level→relaunch persistence loop with the expanded pack. | Yes | agent |
| D016 |  | requirement | R005 | validated | S04/S05 now prove the expanded easy-pack gameplay loop with 50 playable levels, mounted/integrated regression coverage for progression/fail-restart/win/next-level/relaunch persistence, and passing `levelPack.test.ts`, `integratedPlayFlow.test.ts`, `levelsScreen.test.tsx`, `progressPersistence.test.ts`, `starRating.test.ts`, `heartSystem.test.ts`, `movement.test.ts`, plus `npx tsc --noEmit`. | Yes | agent |
| D017 | M003 S01 T01 | architecture | AdMob boundary exposure for game UI | Expose banner rendering through a typed runtime descriptor in hooks/useAd.ts and keep production ad unit IDs in Expo config extra instead of hardcoding SDK calls into screen components. | This keeps the screen and later banner wrapper mock-friendly, prevents silent production fallback to test IDs, and leaves a deterministic debug label that tests can assert without depending on native ad behavior. | Yes | agent |
| D018 | M003/S01 | requirement | R010 | active | M003/S01 integrated the bottom banner ad region into the game screen through a typed runtime descriptor, config-backed ad unit IDs, deterministic fallback messaging, and passing game-screen/levels-screen plus TypeScript verification. This advances the monetization integration requirement, but full validation still depends on the hearts=0 interstitial gate in later slices. | Yes | agent |
| D019 | M003 S02 planning | architecture | FAIL restart ownership during interstitial gating | Keep store/gameStore.ts as the source of FAIL and restart semantics, but let a dedicated InterstitialGate component own when restartLevel() fires by consuming a typed interstitial descriptor/controller from hooks/useAd.ts. | The store already provides correct hearts=0 and restart behavior. Putting ad lifecycle branching in hooks/useAd.ts and restart timing in a gate component preserves the S01 ad-boundary pattern, keeps app/game/[level].tsx mock-friendly, and prevents early restart bypassing the interstitial or duplicating fallback logic in the screen. | Yes | agent |
| D020 | M003/S02 | requirement | R011 | validated | S02 proved that when the interstitial ad cannot be shown or errors during the FAIL gate, the game screen releases through the fallback path and restores PLAYING with hearts=3, moves=0, cleared lastInteraction/lastResolution, and unchanged persisted progress. Evidence: passing gameScreenFailLoopScreen.test.tsx, heartSystem.test.ts, and npx tsc --noEmit. | Yes | agent |
| D021 | M003/S03 | requirement | R010 | validated | S03 closed the monetization proof boundary by passing the mounted GameScreen regression plus persistence/result suites and TypeScript. Evidence now proves banner presence on the game screen, hearts=0 interstitial gate lock-and-release behavior, restart back to PLAYING with hearts reset, no durable progress writes during FAIL/restart, and surviving WIN/progression behavior via `npm test -- --runInBand -- gameScreenFailLoopScreen.test.tsx progressPersistence.test.ts integratedPlayFlow.test.ts` and `npx tsc --noEmit`. | Yes | agent |
| D022 | M004 discussion | scope | M004 scope boundary for repeat-play and release prep | Keep M004 repeat-play work on-device and privacy-minimal: no account system, no personal-information product features, no backend storage, and no analytics-driven expansion as part of this milestone. | The user explicitly wants repeatable on-device content and does not want the app to receive personal information. Locking this boundary now prevents M004 from expanding into live-ops, backend state, or disclosure-heavy product systems that would dilute the release-finish milestone. | Yes | collaborative |
| D023 | M004 discussion | pattern | M004 feedback feel bar | Target clear, restrained feedback rather than loud spectacle: subtle movement cues, stronger collision/clear moments, and verification focused on clarity at the existing game-screen boundary. | The user emphasized 'clear' rather than flashy. This gives S01 a concrete product bar and keeps audio/haptic work aligned with the puzzle-first tone established by the current board and result shell. | Yes | collaborative |
| D024 |  | requirement | R013 | validated | M004/S01 shipped a typed feedback derivation helper, Expo audio+haptics runtime seam, mounted GameScreen feedback diagnostics, and passing slice verification via `npm test -- --runInBand -- gameFeedback.test.tsx gameScreenFailLoopScreen.test.tsx heartSystem.test.ts movement.test.ts boardPresentation.test.ts && npx tsc --noEmit`, proving move/collision/clear/fail-recovery feedback integration without regressing gameplay or monetization flows. | Yes | agent |
| D025 | M004/S02 | requirement | R014 | validated | M004/S02 delivered a local challenge catalog, isolated challenge persistence, source-aware home/challenge entry, and mounted GameScreen reuse for challenge play with replay-after-win and fail-gate recovery. Evidence: `npm test -- --runInBand -- gameScreenFailLoopScreen.test.tsx levelsScreen.test.tsx challengeMode.test.ts integratedPlayFlow.test.ts` passed 28/28 and `npx tsc --noEmit` passed, proving repeatable on-device content can be opened and replayed multiple times per day without backend or account dependence. | Yes | agent |
| D026 |  | requirement | R012 | validated | M004/S03 established a single release-metadata/privacy contract across `app/release/_lib/storeMetadata.ts`, `docs/release/app-store-korea.md`, `app.json`, and the mounted `/release` screen reachable from home, then re-verified the Korean launchability surface with passing `npm test -- --runInBand -- releaseMetadata.test.ts levelsScreen.test.tsx gameScreenFailLoopScreen.test.tsx challengeMode.test.ts integratedPlayFlow.test.ts` and `npx tsc --noEmit`. | Yes | agent |
| D027 | M005 discussion | pattern | M005 result readability bar | Define result-surface success by one-glance understanding: the player can tell win/loss, quality, and next action without explanation, and the screen must not contradict run memory. | The user defined M005 closeout around one-glance comprehension rather than around raw presence of stars, moves, or CTAs. The result surface must therefore be validated against this product bar. | Yes | collaborative |
| D028 | M005/S01 | requirement | R006 | validated | M005/S01 re-proved the mounted GameScreen state-truth contract across PLAYING, BLOCKED, ESCAPED, FAIL, and WIN through visible copy plus deterministic diagnostics, while the closure suite (`npm test -- --runInBand -- gameScreenFailLoopScreen.test.tsx heartSystem.test.ts integratedPlayFlow.test.ts starRating.test.ts boardPresentation.test.ts`) passed 38/38 and workspace TypeScript diagnostics reported no issues. | Yes | agent |
| D029 |  | requirement | R007 | validated | M005/S02 mounted fail-recovery verification now proves the continuity loop end to end: after hearts reach 0 and the interstitial gate releases, GameScreen returns to a fresh PLAYING read with hearts 3/3, moves 0, FAIL UI removed, grid re-enabled, and baseline board/debug copy restored. Evidence: `npm test -- --runInBand -- gameScreenFailLoopScreen.test.tsx heartSystem.test.ts boardPresentation.test.ts gameFeedback.test.tsx` and `npx tsc --noEmit`. | Yes | agent |
| D030 | M005/S03/T02 | requirement | R007 | validated | S03 closed the mounted result-surface contract without further runtime edits: the mounted GameScreen WIN branches, pure helper suites, and integrated progression tests now agree on quality wording, next-action semantics, and diagnostic state lines. Evidence: passing `npm test -- --runInBand -- gameScreenFailLoopScreen.test.tsx starRating.test.ts integratedPlayFlow.test.ts` and `npx tsc --noEmit`. | Yes | agent |
| D031 | M005/S03 | requirement | R007 | validated | S03 closed the mounted result-surface contract without runtime edits: GameScreen WIN branches, deriveStarRatingSummary(), and deriveScreenLevelContext() now agree on one-glance quality wording, next-action semantics, and deterministic feedback/debug lines. Proof: passing `npm test -- --runInBand -- gameScreenFailLoopScreen.test.tsx starRating.test.ts integratedPlayFlow.test.ts` and `npx tsc --noEmit`. | Yes | agent |
| D032 | M006 | scope | M006 scope boundary | Treat M006 as a browser-local verification milestone, not a web product expansion milestone. | The user wants to run the game locally in this PC's browser and directly verify the current product, not add web monetization, web deployment, or parity with the native target. | Yes | collaborative |
| D033 | M006 | architecture | Browser ad/runtime strategy | On web, disable or replace native ad behavior behind a web-safe import boundary instead of trying to run `react-native-google-mobile-ads`. | The actual investigation showed the current Expo web bundle fails at import time on the native ads package, so runtime fallback is not enough. The browser path must avoid bundling unsupported native ad modules while preserving the existing native-focused contract. | Yes | collaborative |
| D034 | M007 | architecture | 가변 길이 열차 좌표 기준 | Train 좌표를 열차의 head(진행 방향 쪽 맨 앞칸) 기준으로 정의하고, 몸통 점유 셀은 방향 반대편으로 계산한다. | 앞부분이 둥근 실루엣, 방향 판독, 탈출 애니메이션, 경계 이탈 타이밍 모두 head 기준이 가장 자연스럽다. 기존 단일 셀 row/col 의미를 앞칸으로 해석하면 길이 확장 시 엔진/렌더링 계산이 단순해진다. | Yes | collaborative |
| D035 | M006/S01 | architecture | M006/S01 web runtime import boundary | Keep ads and gameplay feedback behind shared descriptor hooks plus `.native`/`.web` platform files, and preserve mounted `banner=` / `phase=` / `fallback=` / feedback debug lines as the regression seam. | This slice proved that Expo web export succeeds only when unsupported native packages are removed from the web module graph at import time. Preserving the existing mounted diagnostics lets browser-local verification reuse the same GameScreen and InterstitialGate contracts instead of inventing web-only assertions. | Yes | agent |
| D036 | M006/S01 | requirement | R010 | active | M006/S01 preserved the monetization UI contract across web-safe runtime boundaries: banner diagnostics still render, interstitial phase/fallback diagnostics still drive FAIL recovery, `gameScreenFailLoopScreen.test.tsx` and `npx tsc --noEmit` pass, and `CI=1 npx expo export --platform web` now succeeds without crashing on `react-native-google-mobile-ads`. This advances browser-local compatibility for the monetization seam but does not newly validate native AdMob behavior itself. | Yes | agent |
| D037 | M006/S01 | requirement | R013 | active | M006/S01 preserved gameplay feedback behavior while moving `expo-audio` and `expo-haptics` behind platform files. Focused feedback tests, TypeScript, and web export now prove the browser path no longer crashes on feedback imports, but this slice did not change the already validated native feedback capability contract. | Yes | agent |
| D038 | M006/S02 | architecture | M006/S02 browser proof route handling | Use a dedicated route-only proof flag and stable train selectors for the browser WIN seam; keep normal unlock rules and existing GameScreen diagnostics unchanged. | Live web verification showed the dedicated home CTA fell back to level 1 on cold start because hydration correctly enforced normal easy-pack unlocks. Adding an explicit proof=browser-win route flag let the browser proof open deterministic level 3 without weakening progression rules, while stable train selectors and the existing screen-boundary debug lines kept browser automation and mounted regression coverage aligned. | Yes | agent |
| D039 | M007/S01/T01 | architecture | M007/S01 movement engine seam for variable-length trains | Treat `Train.row`/`col` as head coordinates, derive occupied cells backward from direction, and derive escape/collision checks from the head-forward path only. | This keeps single-cell behavior unchanged while making length-based occupancy, blocking, and escape timing deterministic for downstream store and rendering slices. Collision checks now use the same explicit helper contract that tests can exercise directly. | Yes | agent |
| D040 | M007/S02 | architecture | M007/S02 variable-length rendering seam | Use a shared pure render-geometry helper backed by engine occupancy for Grid placement, Train silhouette sizing, highlight bounds, and tap-target expansion. | S02 proved that rendering and interaction stay deterministic when both Grid and Train consume getTrainRenderGeometry(), which itself reuses getTrainOccupiedCells(). This keeps mounted FAIL/WIN/restart behavior aligned with the head-based engine contract and gives S03 one geometry seam for long-train animation work. | Yes | agent |
| D041 | M007/S03 planning | architecture | M007/S03 long-train exit animation state boundary | Keep long-train exit animation as Grid-owned presentation state derived from render geometry and ESCAPED transitions, and clear it immediately on reset/restart/level changes instead of persisting animation state in Zustand. | S01/S02 already proved that engine/store truth flips to ESCAPED immediately and resetLevel()/restartLevel() restore the original level snapshot synchronously. A presentation-only overlay preserves those rule-truth contracts while allowing the UI to animate the tail off-screen and reset cleanly without changing movement, WIN timing, persistence, or mounted debug seams. | Yes | agent |
| D042 |  | architecture | M007/S03 long-train exit overlay lifetime | Keep exit overlays as Grid-local transient presentation state keyed off ESCAPED transitions, with reset-on-replay/restart/level-change and no store persistence. | The slice proved the pure animation seam and the runtime overlay/reset behavior on disk without changing engine semantics. Store-level ESCAPED/WIN truth remains immediate, while replay/fail recovery can clear overlay residue synchronously. The remaining instability is in the mounted Jest fake-timer harness, not in the gameplay contract itself. | Yes | agent |
| D043 |  | requirement | R009 | validated | S04 rebalanced easy and challenge boards around calibrated mixed-length layouts, preserved stable proof anchors and public ids, and re-verified meaningful par-driven star feedback through passing `levelPack.test.ts`, `starRating.test.ts`, `challengeMode.test.ts`, `heartSystem.test.ts`, `integratedPlayFlow.test.ts`, `gameScreenFailLoopScreen.test.tsx`, and `npx tsc --noEmit`. This now proves players receive durable move-quality feedback against the shipped harder boards rather than trivial single-car layouts. | Yes | agent |
| D044 | M008/S01 planning | architecture | M008/S01 native proof surface | Use SDK-55 dependency normalization plus a checked-in `scripts/verify-ios-native-run.sh` and `docs/ios-native-run.md` as the canonical iOS simulator proof/diagnostic seam for the milestone. | Research showed the first blocker is native build health, not route logic. Closing S01 requires both fixing the package/config contract enough for `npx expo run:ios` to reach simulator install/boot and leaving a repeatable phase-classified operator path that later slices can reuse without rediscovering CLI, port, prebuild, pods, and xcodebuild behavior. | Yes | agent |

---
id: M001
title: "플레이 가능한 코어 퍼즐 루프"
status: complete
completed_at: 2026-03-27T13:44:08.014Z
key_decisions:
  - Stay on Expo SDK 55 and align package versions until `expo-doctor` is clean before treating the baseline as stable — avoids carrying SDK drift into later milestones.
  - Use Expo Router from the start so later slices build on real route files instead of migrating from a temporary single-screen app.
  - Keep movement resolution in a pure engine module (`engine/movement.ts`) that returns deterministic outcomes reusable by UI, store, tests, and future animation work.
  - Expose `status`, `moves`, and per-train `state` directly in the Zustand store so runtime state is inspectable from the UI without recomputation.
  - Represent movement results with shared typed reason codes and collision metadata (`MovementResolution`) instead of ad-hoc booleans.
  - Persist both a concise `lastInteraction` and the full engine `lastResolution` in the store so downstream code can inspect exact blocker coordinates without recomputing gameplay rules.
  - Keep board readability as a pure derived presentation layer (`boardPresentation.ts`) over existing store snapshots — no persisted UI state added.
  - Keep route-adjacent pure helpers under `app/game/_lib/` so Expo Router does not misclassify them as routes during web runtime.
  - Pin `expo.port` to 8081 in `app.json` so CI-style Metro startup proof is deterministic across verification runs.
  - Preserve earlier fixture level ids (1, 3, 4) when expanding content packs so engine/UI regression suites keep trustworthy deterministic anchors.
key_files:
  - engine/movement.ts
  - store/gameStore.ts
  - types/game.ts
  - app/game/[level].tsx
  - app/game/_lib/boardPresentation.ts
  - app/game/_lib/levelProgression.ts
  - app/game/_lib/levelParam.ts
  - components/Grid.tsx
  - components/Train.tsx
  - data/levels/easy.ts
  - app/index.tsx
  - __tests__/movement.test.ts
  - __tests__/boardPresentation.test.ts
  - __tests__/levelPack.test.ts
  - __tests__/integratedPlayFlow.test.ts
  - app.json
lessons_learned:
  - Expo scaffold gotcha: when a repo already contains `.gsd/` metadata, `create-expo-app` must be generated in a temp directory and copied in — it will not initialize cleanly over existing non-Expo files.
  - Expo Router/Jest gotcha: keep route-param coercion and other boundary helpers in pure modules under `_lib/` — this avoids pulling Expo Router runtime into Jest and keeps edge-case coverage independent of the router.
  - Expo CLI gotcha: `--non-interactive` is no longer supported; use `CI=1 npx expo start --offline --clear` for non-interactive startup proof.
  - Expo port prompt gotcha: pin `expo.port` to `8081` in `app.json` to prevent alternate-port prompts in CI-style verification when Metro was previously shifted to another port.
  - First-playable game-store pattern: keep movement resolution in a pure engine module and expose `status`, `moves`, and per-train `state` directly from Zustand so UI and later animation slices inspect gameplay state without recomputing it in components.
  - Collision UX pattern: keep `lastInteraction` for concise player-facing copy and `lastResolution` for full engine truth; have screens read both directly from the store instead of re-deriving blockers, path length, or mutation state in UI code.
  - Board readability pattern: derive all presentation signals (highlighted train, path, blocked, collision, exits) from existing store snapshots in a pure helper — adding no persisted UI state keeps the seam testable and the store authoritative.
  - Content pack pattern: keep next/previous/completed-pack adjacency in a pure data helper (`levelProgression.ts`) so screens consume one contract; preserve fixture ids when expanding so earlier regression suites remain valid.
---

# M001: 플레이 가능한 코어 퍼즐 루프

**Delivered a fully playable tap-to-escape puzzle loop with deterministic collision rules, readable board presentation, a six-level handcrafted pack, and integrated regression coverage — proving the core game feel before any polish layer is added.**

## What Happened

M001 built the foundation of 열차 탈출 from an empty repository to a short but genuinely playable puzzle session across five sequenced slices.

**S01 — 첫 플레이어블 루프** established the architectural skeleton: an Expo Router app shell, a pure `engine/movement.ts` resolving tap-to-escape in deterministic cell steps, a Zustand store exposing `status`/`moves`/per-train `state` directly, and reusable SVG Grid and Train components that render the board without image assets. The home screen routes into `app/game/[level].tsx`, level params are coerced safely in a pure helper, and the WIN state fires when the last train escapes. A 11-case Jest suite locked the escape/win/reset/boundary contracts from the start.

**S02 — 충돌 규칙과 상태 전이** made blocked moves feel explainable rather than arbitrary. Movement outcomes gained shared typed reason codes, traversed path data, and blocker cell metadata. The Zustand store persists both a concise `lastInteraction` for UX copy and a full `lastResolution` snapshot so UI and future diagnostics never recompute engine truth. An on-screen feedback card and compact debug line show outcome/reason/path length/blocker coordinates in the live game screen. A level-4 collision fixture was exposed from the home screen for fast runtime repro. The suite grew to 15 cases covering blocked paths, no-ops, repeated inputs, and WIN/move-count protections.

**S03 — 가독성 있는 보드/열차 표현** added a pure presentation layer on top of the S01/S02 store contracts. `boardPresentation.ts` derives highlighted train, attempted path, blocked path, collision cell, escaped count, exit marker visibility, and hint tone without adding any persisted UI state. Grid gained exit markers, path overlays, blocked-cell emphasis, and collision-cell highlighting. Train gained directional nose geometry and per-state visual styling (selected, blocked, escaped). The game screen now pairs the board with a legend, hint card, and result card. A `boardPresentation.test.ts` suite locked the derived presentation contract with seven regression cases. The Expo port was pinned to 8081 in `app.json` to make CI-style Metro startup deterministic.

**S04 — 짧지만 진짜 풀 수 있는 레벨 묶음** replaced the minimal starter set with six hand-crafted 3×3 and 4×4 easy levels that form a short connected playable arc. A pure `levelProgression.ts` helper handles next/previous/completed-pack lookups so screens consume one authoritative contract. The home screen became a level-entry card list; the game WIN screen shows replay/next buttons and completed-pack messaging. A `levelPack.test.ts` suite with 15 cases locked ordering, adjacency, coercion, last-level, and empty-pack edge cases. Earlier regression suites (movement + board presentation) continued passing unmodified.

**S05 — M001 통합 정리와 플레이 검증** closed the milestone by composing all prior seams into an integrated regression suite (`integratedPlayFlow.test.ts`, 14 cases), aligning game-screen UI badges and copy to the helper-driven progression contract, and verifying that `CI=1 npx expo start --offline --clear --port 8081` reaches `Waiting on http://localhost:8081` deterministically. TypeScript diagnostics were confirmed clean via LSP (a stale relative import in `boardPresentation.ts` was fixed). The authoritative verification contract for the milestone is now: `npm test -- --runInBand -- movement.test.ts boardPresentation.test.ts levelPack.test.ts integratedPlayFlow.test.ts` passing plus pinned-port Metro boot.

## Success Criteria Results

## Success Criteria Results

- **탭 기반 열차 이동** ✅ — S01 ships `engine/movement.ts` + Zustand store + SVG board. Tapping a train resolves its direction, traverses cells, and escapes the board. `npm test movement.test.ts` passes 15 cases including escape, no-op, reset, and WIN transition.

- **셀 기반 충돌 규칙** ✅ — S02 adds structured `MovementResolution` with reason codes, traversed path, and blocker metadata. Level-4 collision fixture is reachable from home. 15 movement contract tests prove blocked/escaped/no-op/WIN-protection determinism.

- **읽기 쉬운 보드 표현** ✅ — S03 ships `boardPresentation.ts` pure helper, Grid/Train overlays, and in-screen legend/hint/result cards. `boardPresentation.test.ts` passes 7 regression cases covering neutral baseline, blocked movement, escaped state, malformed input, and fallbacks.

- **여러 개의 초기 레벨** ✅ — S04 delivers six handcrafted 3×3 and 4×4 easy levels with home entry cards, WIN-screen replay/next controls, and completed-pack messaging. `levelPack.test.ts` passes 15 cases.

- **코어 퍼즐 루프 통합 재검증** ✅ — S05 ships `integratedPlayFlow.test.ts` (14 cases) composing home-entry, fallback, collision, progression, and completed-pack contracts. Metro boots deterministically on port 8081.

- **"짧게라도 재밌다" 증명** ✅ — The six-level pack, readable board, feedback cards, and explicit UAT scripts across all five slices provide sufficient mixed-evidence proof for a first-playable milestone bar. Subjective UX evidence is intentionally hybrid (automation + manual UAT scripts) rather than a recorded device session.

## Definition of Done Results

## Definition of Done Results

- **All slices marked complete** ✅ — S01, S02, S03, S04, S05 all show `[x]` in the roadmap and have corresponding SUMMARY.md + UAT.md artifacts on disk.

- **All slice summaries exist** ✅ — Verified: S01-SUMMARY.md, S02-SUMMARY.md, S03-SUMMARY.md, S04-SUMMARY.md, S05-SUMMARY.md — all present.

- **Non-.gsd/ code changes present** ✅ — `git diff --stat HEAD~5 HEAD -- ':!.gsd/'` shows 14 changed source/test files, 1,211 insertions and 168 deletions across engine, store, components, app screens, data, and test suites.

- **Jest regression suites passing** ✅ — `movement.test.ts` (15 cases), `boardPresentation.test.ts` (7 cases), `levelPack.test.ts` (15 cases), `integratedPlayFlow.test.ts` (14 cases) — all passing per S02/S03/S04/S05 verification evidence.

- **Metro runtime boots deterministically** ✅ — `CI=1 npx expo start --offline --clear --port 8081` reaches `Waiting on http://localhost:8081` with no blocking errors after S05 pinned the port in `app.json`.

- **TypeScript diagnostics clean** ✅ — S05 confirmed LSP-verified clean diagnostics after fixing a stale relative import in `boardPresentation.ts`.

- **Cross-slice integration consistent** ✅ — S02/S03/S04/S05 all consumed prior slice contracts (pure movement seam, store snapshots, board helper, progression helper) without replacing them; fixture ids 1, 3, and 4 were preserved across all content expansions.

- **Validation verdict** ✅ — M001-VALIDATION.md records `verdict: pass` with detailed per-slice delivery audit, cross-slice integration assessment, and requirement coverage analysis.

## Requirement Outcomes

## Requirement Outcomes

- **R001** (첫 플레이어블 루프) — **Active → Validated.** Evidence: `app/index.tsx` routes into `app/game/[level].tsx`; tapping trains updates store state through `engine/movement.ts` until all escape and `status = WIN`; `movement.test.ts` proves the full escape/win flow.

- **R002** (충돌 규칙과 상태 전이) — **Active → Validated.** Evidence: `engine/movement.ts` returns `MovementResolution` with typed reason codes, path data, and blocker metadata; `store/gameStore.ts` persists `lastResolution`/`lastInteraction`; `movement.test.ts` (15 cases) proves blocked/escaped/no-op/WIN determinism.

- **R003** (즉각적인 탭 반응과 상태 가시성) — **Active → Validated.** Evidence: `components/Grid.tsx`, `components/Train.tsx`, and feedback/debug cards on the game screen make every state change immediately inspectable; `npm test movement.test.ts` confirms store updates are synchronous and deterministic.

- **R004** (가독성 있는 보드/열차 표현) — **Active → Validated.** Evidence: `boardPresentation.ts` pure helper, Grid overlays (exit markers, path, blocked, collision), Train direction visuals, in-screen legend/hint/result cards; `boardPresentation.test.ts` (7 cases) proves the presentation contract.

- **R005** (여러 개의 플레이 가능한 레벨) — **Active → Validated.** Evidence: six handcrafted levels in `data/levels/easy.ts`, pure `levelProgression.ts` helper, home multi-level entry cards, WIN-screen replay/next/completed-pack flow; `levelPack.test.ts` (15 cases) and `integratedPlayFlow.test.ts` (14 cases) prove progression contracts end-to-end.

## Deviations

Scaffolding had to be generated in a temp directory and merged into the repo root because `create-expo-app` would not initialize over the existing `.gsd/` metadata. The `--non-interactive` Expo CLI flag was discovered to be removed mid-milestone; verification commands were updated to use `CI=1` from S03 onward. Route-adjacent pure helpers were moved from `app/game/` to `app/game/_lib/` during S03 to prevent Expo Router web from misclassifying them as routes. `app.json` port pinning was added during S03 verification after a non-interactive port prompt blocked startup proof. Runtime proof for M001 is a hybrid of automated Jest coverage plus Metro startup evidence rather than a captured live-device walkthrough, which is appropriate for the first-playable milestone bar but would not be sufficient for a full UAT submission.

## Follow-ups

Phase 2 work for the next milestone: hearts system (3 lives, -1 on collision, FAIL at 0), WIN/FAIL screen transitions with star rating based on `par`, level select screen with progress persistence (AsyncStorage), and expansion to 50 easy levels. The six-level M001 pack is intentionally minimal — the content volume and hearts/fail UX are gated on Phase 2 so the core loop could be proven first without those layers. Also: deprecated React Native Web `shadow*`/`pointerEvents` warnings in the web runtime were noted but not cleaned up — they do not affect the iOS target and can be deferred.