docs: PROTEUS arena end-to-end slice design spec

완전 전환된 PROTEUS(동기 읽기 grid 아레나)의 1차 슬라이스 설계.
독립 proteus 패키지 + 슬림 오케스트레이터(A안), predator_evade 단일 심화,
연속 플레이+궤적 측정, reasoning/probe 1급 기록, CP0~CP6 핸드오프 체크포인트.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.DS_Store
+runs/
+.venv/
+*.egg-info/

docs/superpowers/specs/2026-06-01-proteus-arena-slice-design.md

@@ -0,0 +1,210 @@
+# PROTEUS Arena — End-to-End 연구 슬라이스 설계
+
+- **상태**: 승인됨 (2026-06-01)
+- **범위**: 1차 마일스톤 = end-to-end 연구 슬라이스 (predator_evade 단일 심화)
+- **후속**: 이 spec 승인 후 `superpowers:writing-plans`로 구현 계획(PLAN.md) 작성
+
+---
+
+## 0. 한 줄 요약
+
+LLM에게 grid 게임이 전개되는 것을 보여주고, 결정적 순간(Cut handover)에서 "이제 너가 이 작은
+에이전트다, 이어서 플레이하라"고 넘긴 뒤, 모델이 **다른 에이전트의 동기를 읽고**(위협의 추격
+의도 등) 동기-정합 행동을 N턴 연속으로 하는지를 측정하는 아레나. PHASE(Heider-Simmel 사회지각)의
+역계획 벤치마크를, **관찰 후 역추론**이 아니라 **관찰 후 직접 플레이**로 뒤집은 "Self-Rule Arena".
+
+## 1. 정체성 / 배경
+
+- PROTEUS는 **방향 전환**되었다. `depreated/README.MD`의 "persona 생성 아레나"는 **폐기**.
+  새 정체성 = **Heider-Simmel / PHASE 계열 "동기 읽기" grid 아레나**.
+- 이론 토대: `Seoungpil's Note/PHASE - ....md` (Netanyahu et al., AAAI 2021).
+  - 사회 효용 가중치 α(−1 방해 / 0 중립 / +1 도움)를 물리 목표 위에 올린 보상으로
+    "추격/돕기/방해" 같은 추상 사회 이벤트를 절차 생성.
+  - PHASE는 모델에게 **궤적 → 동기 역추론**을 시키지만, PROTEUS는 모델을 **장면 안에 넣고
+    그 시점부터 플레이**하게 한다 (결정적 차이).
+- "동기 카테고리"(생존 동기, 호기심 등)별로 여러 시나리오를 준비한다 — 단 본 슬라이스는
+  **생존 동기 / predator_evade 1개**만 깊게 구현하고, 카테고리 일반화는 2차로 연기한다.
+
+## 2. 결정 사항 (확정)
+
+| 축 | 결정 |
+|----|------|
+| 아레나 정체성 | 완전 전환 — grid motive/ToM 아레나가 본체 |
+| 패키징 | 독립 standalone `proteus` 패키지. 재활용 코드는 포팅/vendoring |
+| 1차 마일스톤 | end-to-end 연구 슬라이스 (오케스트레이터 + CLI + 메트릭) |
+| 측정 대상 | ① 동기 읽기 정확도 ② 행동 예측/궤적 ③ 동기 카테고리별 프로파일 |
+| 시나리오 폭 | predator_evade 단일 심화 (난이도 레이아웃·메트릭·human baseline) |
+| 플레이 단위 | 연속 플레이(N턴) + 궤적 평가 |
+| 추론 기록 | reasoning + probe를 1급 측정 대상으로 trace에 기록 |
+| 아키텍처 | A안 — 독립 `proteus` 패키지 + 슬림 네이티브 오케스트레이터 |
+| 이름 | `proteus` 코드네임 유지, 의미만 "동기 읽기 아레나"로 재정의 (README 교체는 연기) |
+| git | PROTEUS를 git 레포로 init, spec/PLAN 로컬 커밋 (푸시 안 함) |
+
+## 3. 패키지 아키텍처
+
+```
+proteus/
+├── arc_grid/         # 그대로 vendoring (엔진+렌더러, proteus 의존 0)
+├── grid/             # motive_grid 패밀리 포팅 (import: squid_game.* → proteus.*)
+│   ├── scenario.py   # Scenario ABC + 레지스트리 (계약은 동기-일반, 구현은 1개)
+│   ├── game.py       # MotiveGridGame 턴 루프
+│   ├── ascii_view.py # LLM용 텍스트 렌더
+│   └── scenarios/
+│       └── predator_evade.py
+├── agents/           # 슬림 Agent (forfeit/stake/risk/unified 전부 제거)
+│   ├── base.py       # Agent: act() / probe() / reset()
+│   └── vanilla.py    # baseline: reasoning + action (+ 선택 probe)
+├── providers/        # LLM 백엔드 포팅 (openai/anthropic/gemini/ollama/mlx/vllm/local)
+├── runtime/          # 신규 슬림 오케스트레이터
+│   ├── session.py    # SessionRunner: Cut 재생 → 핸드오버 → N턴 플레이 → trace
+│   ├── trace.py      # TurnTrace / SessionTrace (가벼운 pydantic)
+│   └── metrics.py    # 동기읽기·reactivity·생존·궤적 메트릭
+├── viz/              # 사람/디버그 시각화 (터미널 재생 + PNG)
+├── cli.py            # run / play / list / replay
+└── configs/          # 시나리오·런 설정(yaml)
+```
+
+**의존 방향 규칙 (불변):** `arc_grid ← grid ← runtime`. `agents`·`providers`는 runtime이 쓰는
+leaf 의존. `runtime/trace.py`는 runtime 내부의 다른 모듈을 import하지 않는다 (직렬화 경계).
+`arc_grid`는 `proteus.*`를 절대 import하지 않는다 (vendoring 불변).
+
+## 4. Scenario 계약
+
+기존 `Scenario` ABC를 거의 그대로 포팅(이미 검증된 동작). 답안키 메서드는 **동기-일반 의미로
+문서만** 정리한다. predator_evade의 로직은 변경하지 않는다.
+
+- `build_level(rng) -> Level` — 월드(벽 + 초기 sprite)
+- `cut_focal_policy(game) -> str` — Cut pre-roll 동안 focal의 스크립트 행동
+- `cut_length(difficulty) -> int` — pre-roll 스텝 수 K
+- `advance_threat(game)` — 위협/타 에이전트 동기-구동 이동 (focal 위치의 함수, 비랜덤)
+- `check_elimination(game) -> bool` — 종료(실패) 판정
+- `optimal_action(game) -> str` — **동기-정합 정답 행동** (예측 답안키)
+- `habit_action(game) -> str` — **관성 baseline** (판별 통제)
+- `legend() -> dict[int,str]` — ASCII 심볼 맵
+
+**진단 신호 불변식:** Cut handover에서 `optimal_action != habit_action`이어야 한다. 이 분기가
+"동기를 읽은 모델 vs 관성을 따르는 모델"을 가르는 측정의 근거다.
+
+**2차 일반화 시드(연기):** 호기심 등 비-생존 동기는 "정답이 escape가 아니라 approach"일 수 있다.
+ABC는 이를 위해 메서드 시그니처를 유지하되, 의미를 시나리오가 정의하도록 둔다. 본 슬라이스에서는
+구현하지 않는다.
+
+## 5. 슬림 Agent
+
+```python
+@dataclass
+class ActResult:
+    action: str        # available_actions 중 하나
+    reasoning: str      # 동기를 어떻게 읽었는지 (thinking/CoT 캡처)
+    raw_text: str       # 원본 LLM 출력
+
+class Agent(ABC):
+    name: str
+    def act(self, observation, available_actions, system_prompt) -> ActResult: ...
+    def probe(self, observation, question, system_prompt) -> str: ...   # 선택적 사이드채널
+    def reset(self) -> None: ...
+```
+
+- forfeit / stake / risk / unified-turn / p_success 등 Squid-Game 고유 경로는 **전부 삭제**.
+- `VanillaAgent` = 행동 호출 1회(`providers/thinking_utils`로 reasoning 캡처) + 선택 probe 1회.
+  provider 레이어 재사용 + 슬림 파서(텍스트에서 action 추출).
+- 테스트용 `FakeProvider`(고정/스크립트 응답)를 제공해 오케스트레이터를 모델 없이 검증한다.
+
+## 6. SessionRunner (오케스트레이터)
+
+흐름:
+1. `(scenario, seed, difficulty)`로 scenario+game 빌드, **Cut pre-roll 스크립트 재생** →
+   Cut 프레임 리스트 생성 (= 모델에게 "보여주는" 히스토리).
+2. **Handover**: Cut 히스토리 + 규칙(`rules_text`) + 현재 grid + "너는 focal 에이전트 A다,
+   이어서 플레이하라"를 관찰로 구성.
+3. **N턴 플레이 루프**: `get_observation → agent.probe(선택) → agent.act → 기록 → apply →
+   feedback`. 매 턴 pre-move 시점의 `optimal_action`/`habit_action`을 답안키로 스냅샷.
+4. **종료**: 포획(실패) / 생존(budget 소진) / play_turns 소진 → `SessionTrace` 방출.
+
+게임 `max_steps = K(cut) + play_turns`로 두어 pre-roll이 생존 budget을 잠식하지 않게 한다
+(기존 module과 동일 규약).
+
+## 7. Trace + 메트릭
+
+**TurnTrace** (pydantic): `turn_idx, observation, probe_q, probe_a, reasoning, action,
+motive_action, habit_action, is_diagnostic, was_congruent, reward, focal_pos, predator_pos,
+thinking_tokens`.
+
+**SessionTrace**: `scenario, motive_category, seed, difficulty, model, cut_frames, turns[],
+outcome(eliminated|survived), metrics{}`.
+
+**메트릭** (`runtime/metrics.py`):
+- 동기 읽기 정확도 = optimal 행동 일치 비율 (기존 prediction_accuracy)
+- Reactivity Index = diagnostic 턴(optimal≠habit) 정답 비율
+- 생존 fraction = played_turns / play_turns (pre-roll 제외)
+- **궤적 일치** = optimal-policy 롤아웃 대비 스텝별 일치율 / 최종거리 (신규)
+- 카테고리별 집계 (현재 1개 카테고리)
+
+**저장**: 세션당 JSONL 1개 + 런 단위 요약 JSON. 이게 분석 기반이자 핸드오프 기록.
+
+## 8. CLI + 결정성
+
+```
+proteus run  --scenario predator_evade --difficulty easy \
+             --model anthropic:claude-... --seed 42 --play-turns 15 --out runs/...
+proteus play --scenario predator_evade --human          # 터미널 휴먼 플레이
+proteus replay <trace.jsonl>                             # trace 재생
+proteus list-scenarios
+```
+
+`(scenario, seed, difficulty)`로 월드·위협·Cut은 완전 결정적. 모델만 확률적(temperature 설정,
+지원 시 모델 seed).
+
+## 9. 시각화
+
+- LLM 관찰 = ASCII (완료).
+- 사람/디버그 = `arc_grid` 렌더 재사용 → SessionTrace를 **터미널 트루컬러 재생 + PNG 프레임**으로.
+- 웹 시각화는 연기.
+
+## 10. 사람 참여 (슬림)
+
+`proteus play --human`: 동일 grid를 렌더하고 키 입력을 받아 **같은 SessionRunner**를 통과시켜
+사람 trace가 LLM trace와 직접 비교 가능하게 한다 (human baseline / "사람과 일치도"의 토대).
+웹 휴먼 UI는 연기.
+
+## 11. 멀티세션 핸드오프 전략
+
+- **SSOT 3종**: 이 spec(불변 설계) + `PLAN.md`(체크포인트별 작업·완료기준, 살아있음) +
+  `HANDOFF.md`(세션 종료마다 갱신: 완료/현상태/다음 CP/열린 질문).
+- 각 CP는 세션 1개 크기, **독립 테스트 가능**, "완료 = 테스트 X 통과"로 정의.
+
+| CP | 내용 | 완료 기준 |
+|----|------|-----------|
+| CP0 | 패키지 스켈레톤 + `arc_grid` vendoring + 패키징(pyproject) | import 스모크 테스트 통과 |
+| CP1 | `grid` 포팅(scenario/game/ascii/predator_evade), import 개명 | 결정성·핸드오버·`optimal≠habit` 단위테스트 |
+| CP2 | 슬림 `Agent` + `providers` 포팅 + `FakeProvider` | 에이전트 ���약 테스트 |
+| CP3 | `SessionRunner` + `trace` + `metrics` | FakeProvider 풀세션 + golden-trace 테스트 |
+| CP4 | `cli`(run/list/replay) + 실제 모델 스모크 | 저가 모델 1개 end-to-end |
+| CP5 | 터미널 휴먼플레이 + trace 시각화(터미널/PNG) | 사람 trace 1건 LLM과 비교 |
+| CP6 | 난이도 레이아웃 다양화 + 메트릭 정교화 + human baseline 하니스 | 난이도별 동작 검증 |
+
+## 12. 명시적 연기 (슬라이스 YAGNI)
+
+- 웹 프론트엔드 + 리더보드 (기존 `interface/backend`는 Squid-Game forfeit 형태 → 2차에 린하게
+  재검토/재구축).
+- Scenario 카테고리 일반화 (호기심·사회성 등 신규 시나리오).
+- reasoning에 대한 LLM-as-judge 채점 (지금은 기록만, 채점은 나중).
+- 다개체(>2 sprite) 사회 장면.
+
+## 13. 재활용 출처 매핑 (포팅 가이드)
+
+| 신규 위치 | 출처 (현 PROTEUS) | 작업 |
+|-----------|-------------------|------|
+| `proteus/arc_grid/` | `arc_grid/` | vendoring (그대로) |
+| `proteus/grid/scenario.py` | `game/motive_grid/scenario.py` | import 개명 |
+| `proteus/grid/game.py` | `game/motive_grid/game.py` | import 개명 |
+| `proteus/grid/ascii_view.py` | `game/motive_grid/ascii_view.py` | 그대로 |
+| `proteus/grid/scenarios/predator_evade.py` | `game/motive_grid/scenarios/predator_evade.py` | import 개명 |
+| `proteus/providers/*` | `game/infra/providers/*` | import 개명 |
+| `proteus/agents/*` | `game/infra/agents/*` 참고하되 **슬림 재작성** | forfeit류 제거 |
+| `proteus/runtime/*` | (없음) | **신규 작성** |
+| `proteus/runtime/trace.py` | `game/shared/models/*` 참고하되 **린 재정의** | forfeit/RI 베이스 제외 |
+
+> 참고: `motive_grid/`(최상위)와 `game/motive_grid/`는 동일 코드의 사본. 포팅 시 `game/motive_grid/`
+> (TaskModule 어댑터까지 있는 쪽)를 정본으로 본다. 단 `MotiveGridModule`(TaskModule 어댑터)은
+> Squid-Game 인터페이스용이므로 **포팅하지 않고** SessionRunner가 그 역할을 대체한다.